跳到主要内容

Kopi Agent S6 容器进程监管

修改、调试或扩展 KOPI AI AGENT Docker 镜像中的 s6-overlay 监管树 —— 添加新服务、调试配置文件网关、理解 Architecture B 主程序模式。

Skill 元数据​

来源Optional(可选)— 使用 kopi skills install official/devops/kopi-s6-container-supervision 安装
路径optional-skills/devops/kopi-s6-container-supervision
版本1.0.0
作者KOPI AI AGENT
许可证MIT
平台linux
标签docker, s6, supervision, gateway, profiles
相关 skillskopi-ai-agent, kopi-ai-agent-dev

参考:完整 SKILL.md​

信息

以下是当此 skill 被触发时,Kopi Agent 加载的完整 skill 定义。这就是该 skill 激活时 agent 所看到的指令。

Kopi Agent s6-overlay 容器进程监管

何时使用此 skill​

在以下场景中加载此 skill:

  • 在 Kopi Agent Docker 镜像中添加或删除静态服务(即每次容器启动时都应被监管的内容,例如仪表盘)
  • 诊断每个配置文件的网关为何无法启动、重启,或无法在 docker restart 之后存活
  • 理解为何容器的 CMD 是 /opt/kopi/docker/main-wrapper.sh,以及带前导短横线的参数如何传递给用户的程序
  • 修改 cont-init.d 引导脚本(UID 重映射、卷种子数据、配置文件协调)
  • 更改按配置文件网关渲染的运行脚本(Phase 4)

如果你只是在使用 KOPI AI AGENT 并想使用 Docker,请改为参阅 website/docs/user-guide/docker.md。

架构概览​

/init                                  ← PID 1 (s6-overlay v3.2.3.0)
├── cont-init.d ← oneshot setup, runs as root
│ ├── 01-kopi-setup ← docker/stage2-hook.sh
│ │ ├── UID/GID remap
│ │ ├── chown /opt/data
│ │ ├── chown /opt/data/profiles (every boot)
│ │ ├── seed .env / config.yaml / SOUL.md
│ │ └── skills_sync.py
│ └── 02-reconcile-profiles ← kopi_cli.container_boot
│ ├── chown /run/service (kopi-writable for runtime register)
│ └── walk $KOPI_HOME/profiles/<name>/gateway_state.json
│ → recreate /run/service/gateway-<name>/
│ → auto-start only those with prior_state == "running"
│
├── s6-rc.d (static services, in /etc/s6-overlay/s6-rc.d/)
│ ├── main-kopi/run ← exec sleep infinity (no-op slot)
│ └── dashboard/run ← if KOPI_DASHBOARD=1, runs `kopi dashboard`
│
├── /run/service (s6-svscan watches; tmpfs)
│ ├── gateway-coder/ ← runtime-registered per-profile
│ │ ├── type ("longrun")
│ │ ├── run ("#!/command/with-contenv sh ... exec s6-setuidgid kopi kopi -p coder gateway run")
│ │ ├── down (marker — present means "registered but don't auto-start")
│ │ └── log/run (s6-log → $KOPI_HOME/logs/gateways/coder/current)
│ └── ...
│
└── CMD ("main program") ← /opt/kopi/docker/main-wrapper.sh
└── routes user args: bare exec | kopi subcommand | kopi (no args)
— exec'd by /init with stdin/stdout/stderr inherited (TTY for --tui)

关键文件​

路径作用
Dockerfiles6-overlay 安装 + cont-init.d 接线 + ENTRYPOINT ["/init", "/opt/kopi/docker/main-wrapper.sh"]
docker/stage2-hook.sh“旧的 entrypoint 逻辑” —— UID 重映射、chown、种子数据、skills 同步。以 cont-init.d/01-kopi-setup 的形式运行。
docker/cont-init.d/02-reconcile-profiles每次启动时调用 kopi_cli.container_boot,以从持久化卷中恢复配置文件网关槽位。
docker/main-wrapper.sh容器的 CMD。路由用户参数,通过 s6-setuidgid 切换到 kopi,然后 exec 所选程序。
docker/s6-rc.d/main-kopi/run空操作的 sleep infinity —— 保留该槽位是为了让 s6-rc user bundle 有效;主 kopi 以 CMD 的形式运行,而不是作为被监管的服务。
docker/s6-rc.d/dashboard/run条件服务 —— 除非 KOPI_DASHBOARD 为真值,否则 exec sleep infinity。
docker/entrypoint.sh向后兼容的垫片,exec stage2 钩子。硬编码了旧 entrypoint 路径的外部脚本仍可正常工作。
kopi_cli/service_manager.pyS6ServiceManager:register_profile_gateway、unregister_profile_gateway、start/stop/restart/is_running、list_profile_gateways。
kopi_cli/container_boot.pyreconcile_profile_gateways() —— 遍历持久化的 profiles,重新生成 s6 槽位,并生成 container-boot.log。
kopi_cli/gateway.py::_dispatch_via_service_manager_if_s6在容器中运行时拦截 kopi gateway start/stop/restart 并将其路由到 s6。

为何采用 Architecture B(CMD 作为主程序,而非由 s6 监管)​

最初的方案(v1–v3)要求主 kopi 作为一个受监管的 s6-rc 服务运行。但 s6-overlay v3 中两个真实的机制使其无法实现:

  1. cont-init.d 脚本收不到 CMD 参数 —— 因此 stage2 钩子无法解析 docker run <image> chat -q "hi" 来为服务的 run 脚本设置 KOPI_ARGS 供其读取。
  2. /run/s6/basedir/bin/halt 不会传递写入 /run/s6-linux-init-container-results/exitcode 的退出码。无论写入什么,容器始终以 143(SIGTERM)退出。这一点已由 skarnet(s6 作者)在 issue #477 中确认:"if you want a container shutdown, you need to either have your CMD exit, or, if you have no CMD, write the container exit code you want then call halt"(“如果你想要容器关闭,要么让你的 CMD 退出,要么(在没有 CMD 的情况下)写入你想要的容器退出码然后调用 halt”)。

因此我们采用了 s6-overlay 原生的 CMD 模式:ENTRYPOINT ["/init", "/opt/kopi/docker/main-wrapper.sh"]。/init 会自动将该包装器置于用户参数之前 —— 于是 docker run <image> --version 变成 /init main-wrapper.sh --version,而 --version 不会被 /init 的 POSIX shell 拦截。该包装器通过 s6-setuidgid 切换到 kopi,然后 exec 所选程序。程序的退出码即成为容器的退出码,与 pre-s6 的 tini 行为契约完全一致。

权衡之处在于:主 kopi 在 s6 下不受监管。这与它在 tini(pre-s6 镜像)下的行为完全一致。仪表盘监管是唯一新增的保证 —— 而 /run/service/ 下的按配置文件网关则获得完整的监管。

快速操作示例​

验证运行中的容器里 s6 是 PID 1​

docker exec <c> sh -c 'cat /proc/1/comm; readlink /proc/1/exe'
# Expect: s6-svscan or init / /package/admin/s6/.../s6-svscan

查看某个配置文件网关服务​

# /command/ isn't on docker-exec PATH — use absolute path
docker exec <c> /command/s6-svstat /run/service/gateway-<name>
# "up (pid …) … seconds" → running
# "down (exitcode N) … seconds, normally up, want up, …" → s6 wants it up but the process keeps exiting (crash loop)
# "down … normally up, ready …" → user stopped it

手动启动/停止某个服务​

docker exec <c> /command/s6-svc -u /run/service/gateway-<name>   # up
docker exec <c> /command/s6-svc -d /run/service/gateway-<name> # down
docker exec <c> /command/s6-svc -t /run/service/gateway-<name> # SIGTERM (restart)

查看 cont-init 协调器日志​

docker exec <c> tail -n 50 /opt/data/logs/container-boot.log
# 2026-05-21T06:18:05+0000 profile=coder prior_state=running action=started
# 2026-05-21T06:18:05+0000 profile=writer prior_state=stopped action=registered

添加新的静态服务​

  1. 使用 longrun\n 和 docker/s6-rc.d/<name>/run 创建 docker/s6-rc.d/<name>/type(使用 #!/command/with-contenv sh + # shellcheck shell=sh)。
  2. 在 run 的开头通过 s6-setuidgid hermes 切换到 kopi(除非你确实需要 root)。
  3. 创建空的 docker/s6-rc.d/<name>/dependencies.d/base,使其等待基础 bundle。
  4. 创建空的 docker/s6-rc.d/user/contents.d/<name>,使其加入 user bundle。
  5. Dockerfile 中的 COPY docker/s6-rc.d/ 会自动识别它 —— 无需其他改动。

更改按配置文件网关的运行命令​

在 kopi_cli/service_manager.py 中编辑 S6ServiceManager._render_run_script。该函数在启动协调期间也会被 kopi_cli/container_boot.py::_register_service 调用,因此它是唯一的真实来源。请同步更新 tests/kopi_cli/test_service_manager.py::test_s6_register_creates_service_dir_and_triggers_scan 中相应的断言。

运行 docker 测试套件​

docker build -t kopi-ai-agent-harness:latest .
KOPI_TEST_IMAGE=kopi-ai-agent-harness:latest scripts/run_tests.sh tests/docker/ -v
# Expect 19 passed, 0 xfailed against the s6 image

该测试套件位于 tests/docker/,在 Docker 不可用时会跳过。每个测试的超时时间已提高到 180 秒(参见 tests/docker/conftest.py)。

常见问题​

通过 docker exec 时报 "command not found"​

/command/(s6-overlay 存放其二进制文件的目录)只对监督树派生的进程(服务、cont-init.d、main-wrapper.sh)加入 PATH。docker exec <c> s6-svstat … 会因 "command not found" 而失败;始终使用绝对路径 /command/s6-svstat。kopi 二进制文件之所以可用,是因为 Dockerfile 将 /opt/kopi/.venv/bin 添加到了运行时的 ENV PATH 中。

Profile 目录的属主问题​

cont-init 调和器(reconciler)以 kopi 身份运行(在 02-reconcile-profiles 中为 s6-setuidgid hermes)。如果某个 profile 目录变成了 root 所有(例如因为 docker exec <c> kopi profile create … 默认以 root 身份运行),调和器将无法读取 SOUL.md,并以 PermissionError 失败。缓解措施:stage2-hook.sh 会在每次启动时幂等地将 $KOPI_HOME/profiles 的属主 chown 给 kopi。请勿删除该代码块。

docker exec 写入的文件属主为 root​

docker exec 默认为 root。可以传入 --user hermes,或依赖下次重启时 stage2 的 chown 清扫。请勿以 root 身份手动向 $KOPI_HOME/profiles/<name>/ 下写入文件 —— 下一轮调和会清扫这些文件,但进行中的操作可能会遇到权限错误。

服务槽位存在,但 s6-svstat 显示 "s6-supervise not running"​

服务目录位于 tmpfs 上,在容器重启时被清空。要么 cont-init 调和器尚未运行(在 docker restart 之后稍等片刻),要么它运行失败了。请检查 docker logs <c> | grep '02-reconcile'。

网关启动后立即退出(svstat 中为 down (exitcode 1))​

最可能的原因是 profile 没有配置模型或认证。服务槽位是正确的 —— 问题在于网关本身未配置。请先运行 kopi -p <profile> setup。s6 监督器会持续重启它;这正是预期行为(当你修复配置后,下一次尝试就会成功并保持运行)。

调和器跳过了某个 profile​

调和器以 SOUL.md 的存在作为"真实 profile"的标记。kopi profile create 总会写入该文件。如果某个 profile 目录缺少 SOUL.md(目录游离、恢复不完整、备份进行中),调和器会有意跳过它。添加一个 SOUL.md(即使为空)即可重新纳入。

"救命,容器以 143 退出了!"​

检查是否有东西调用了 s6-svscanctl -t 或 /run/s6/basedir/bin/halt —— 两者都会让 /init 开始第 3 阶段关机,但返回 143(SIGTERM)而不是期望的退出码。这就是第 2 阶段从方案 A 到方案 B 的架构调整。要让容器带真实的退出码关闭,你必须让 CMD(main-wrapper.sh)正常退出;不要试图在 finish 脚本中控制退出。

相关 skill​

  • kopi-ai-agent-dev:kopi-ai-agent 代码库的通用导航
  • kopi-tool-quirks:Kopi Agent-tool 的具体变通方法(sed/grep 等)—— 在调试 s6 栈与 kopi 内置工具的交互时加载。