From 565f302e5292e9ccb843868128b567a15a6fe809 Mon Sep 17 00:00:00 2001 From: Kris Date: Tue, 28 Oct 2025 21:58:50 +0800 Subject: [PATCH] doc: Synchronize README.cn.md content with English version (#169) This PR comprehensively reviews and synchronizes the Chinese documentation (README.cn.md) with the English version (README.md) to ensure technical accuracy and consistency. --- README.cn.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/README.cn.md b/README.cn.md index 8a94815..3c660a5 100644 --- a/README.cn.md +++ b/README.cn.md @@ -29,8 +29,8 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr - DELETE /file/:fileId 删除文件 ID 指定的文件 - /ws /run 接口的 WebSocket 版 - /stream 运行交互式命令。支持流式 api -- /version 得到本程序编译版本和 go 语言运行时版本 - - /config 得到本程序部分运行参数,包括沙箱详细参数 +- /version 获取构建的 Git 版本 (例如 v1.9.0) 以及运行时信息 (go 版本, 操作系统, 平台) + - /config 获取部分配置信息 (例如 fileStorePath, runnerConfig) 以及支持的功能特性 ### REST API 接口定义 @@ -70,7 +70,7 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr - 默认监听地址是 `localhost:5050`,使用 `-http-addr` 指定 - 默认 gRPC 接口处于关闭状态,使用 `-enable-grpc` 开启 - 默认 gRPC 监听地址是 `localhost:5051` ,使用 `-grpc-addr` 指定 -- 默认日志等级是 info ,使用 `-silent` 关闭 或 使用 `-release` 开启 release 级别日志 +- 默认日志等级是 info ,使用 `-silent` 关闭 或 使用 `-release` 开启 release 级别日志(在 docker 中会自动开启) - 默认没有开启鉴权,使用 `-auth-token` 指定令牌鉴权 - 默认没有开启 go 语言调试接口(`localhost:5052/debug`),使用 `-enable-debug` 开启,同时将日志层级设为 Debug - 默认没有开启 prometheus 监控接口,使用 `-enable-metrics` 开启 `localhost:5052/metrics` @@ -82,7 +82,7 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr - 使用 `-mount-conf` 指定沙箱文件系统挂载细节,详细请参见 [文件系统挂载](https://docs.goj.ac/cn/mount) (仅 Linux) - 使用 `-file-timeout` 指定文件存储文件最大时间。超出时间的文件将会删除。(例如指定 `30m` 时,缓存文件将在创建后 30 分钟删除) - 默认文件存储在共享内存文件系统中(`/dev/shm/`),可以使用 `-dir` 指定另外的本地目录为文件存储 -- 默认最大输出限制为 `256MiB`,使用 `-output-limit` 指定 +- 默认最大输出限制为 `256MiB`,使用 `-output-limit` 指定 POSIX rlimit 的输出限制 - 默认最大 `copyOut` 文件大小为 `64MiB` ,使用 `-copy-out-limit` 指定 可以[在此查看更多配置文档](https://docs.goj.ac/cn/configuration)。 @@ -114,9 +114,7 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr - Dangerous Syscall: 程序被 `seccomp` 过滤器结束(默认不启用) - Internal Error: - 指定程序路径不存在 - - 或者容器创建失败 - - 比如使用非特权 docker - - 或者在个人目录下以 root 权限运行 + - 或者容器创建失败(比如使用非特权 docker) - 或者其他错误 ### 容器的文件系统 @@ -148,7 +146,7 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr `go-judge` 目前已经支持 cgroup v2 鉴于越来越多的 Linux 发行版默认启用 cgroup v2 而不是 v1 (比如 Ubuntu 21.10+,Fedora 31+)。然而,对于内核版本小于 5.19 的版本,因为 cgroup v2 在内存控制器里面缺少 `memory.max_usage_in_bytes`,内存使用量计数会转而采用 `maxrss` 指标。这项指标会显示的比使用 cgroup v1 时候要稍多,在运行使用内存较少的程序时比较明显。对于内核版本大于或等于 5.19 的版本,`memory.peak` 会被采用。 -同时,如果本程序在容器中运行,容器中的进程会被移到 `/api` cgroup v2 控制器中来开启 cgroup v2 嵌套支持。 +同时,如果本程序在容器中运行,容器中的进程会被移到 /api cgroup v2 层级中来开启 cgroup v2 嵌套支持。 在 `systemd` 为 `init` 的发行版中运行时,`go-judge` 会使用 `dbus` 通知 `systemd` 来创建一个临时 `scope` 作为 `cgroup` 的根。 @@ -156,11 +154,11 @@ docker run -it --rm --privileged --shm-size=256m -p 5050:5050 --name=go-judge cr #### 内存使用 -控制进程通常会使用 `20M` 内存,每个容器进程最大会使用 `20M` 内存,每个请求最大会使用 `2 * 16M` + 总 `copyOutMax` 限制 * 2 内存。请注意,缓存文件会存储在宿主机的共享内存中 (`/dev/shm`),请保证其大小足够存储运行时最大可能文件。 +控制进程通常会使用 `20M` 内存。每个容器进程通常会占用 `20M` 内存 + 临时文件系统 (tmpfs) 大小 `2 * 128M`。对于每个请求,它将占用 用户程序限制的最大内存 + 额外限制 (`16k`) + 总 copy out 最大限制。请注意,缓存文件存储在宿主机的共享内存中 (`/dev/shm`),因此请确保分配了足够的空间。 -比方说当同时请求数最大为 4 的时候,本程序最大会占用 `60 + (20+32) * 4M = 268M` + 总 copy out max 限制 * 8 内存 + 总运行程序最大内存限制。 +比方说当并发数(concurrency)为 4 时,容器本身可能占用高达 `60 + (20+32) * 4M = 268M` + 4 \* 总 copy out 限制 + 总请求的最大内存限制。 -因为 go 语言 runtime 垃圾收集算法实现,有时并不会主动归还占用内存。这种情况可能会引发 OOM Killer 杀死进程,因此引入了一个后台检查线程用于在堆内存占用高时强制垃圾收集和归还内存。 +由于 Go 语言运行时(runtime)的限制,内存并不会自动返回给操作系统,这可能会导致 OOM Killer 杀死进程。因此引入了一个后台工作线程,用于检查堆内存使用情况并在必要时调用垃圾收集(GC)。 -- `-force-gc-target` 默认 `20m`, 堆内存使用超过该值是强制垃圾收集和归还内存 -- `-force-gc-interval` 默认 `5s`, 为后台线程检查的频繁程度 +- `-force-gc-target` 默认 `20m`,触发 GC 的最小堆内存使用量 +- `-force-gc-interval` 默认 `5s`,检查内存使用情况的间隔时间