Docker（社区维护）

当宿主机无法提供 systemd user session 时，可以使用社区维护的 Docker 封装运行 Orbi。仓库里的 Docker 部署外挂 3rd/docker/ 是社区维护、非官方支持的薄封装：一个 Linux 容器，跑的是未改动的官方部署——systemd 作为 PID 1 带真实 user manager、官方 systemd/[email protected] + [email protected] user unit、可编辑 CLI 安装和幂等的 orbi setup。它不是第二套部署模型：有 systemd user session 的 Linux 主机请始终优先走官方路径（见快速开始）——两条路径二选一，不要对同一个任务池并存。

什么时候用它

宿主机没有 user systemd session（NAS、容器平台、受限的云主机）但能跑 Docker。
想把 runner 与宿主机用户会话隔离。

快速开始

拉取发布镜像，然后用一条 docker run 启动 runner。两个仓库源携带相同 tag：latest 和去掉 v 前缀的发布号（如 0.5.17）。

docker pull ghcr.io/orbi-build/orbi:latest
# Docker Hub 上的同一镜像：
docker pull docker.io/orbibuild/orbi:latest

一条 docker run 即可达成交付：GitHub token、任务池和模型 provider 全部来自环境变量，entrypoint 在首次启动时把它们写进 deploy home 的 env 文件、生成的 orbi.toml 和生成的 pi-providers.json（已存在的文件绝不覆盖）。替换三个带引号的值——token、repo、key；DeepSeek 端点只是示例，任何 OpenAI 兼容端点都用同样四个变量（ORBI_PI_PROVIDER、ORBI_PI_MODEL、ORBI_PI_BASE_URL、 ORBI_PI_API_KEY）。从 Docker Hub 拉取的话，把镜像引用换成 docker.io/orbibuild/orbi:latest。

# 可选模型上限及默认值——仅在需要覆盖时，把对应的 -e 行加进下面的
# 命令（放在镜像引用之前）：
#   -e ORBI_PI_API=openai-completions
#   -e ORBI_PI_CONTEXT_WINDOW=128000
#   -e ORBI_PI_MAX_TOKENS=16384
docker run -d --name orbi \
  --stop-signal SIGRTMIN+3 \
  --tmpfs /run --tmpfs /tmp \
  --cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
  -v orbi-deploy:/orbi \
  -v orbi-work:/work \
  -e GH_TOKEN="github_pat_xxx" \
  -e ORBI_SOURCE_REPO="OWNER/REPO" \
  -e ORBI_PI_PROVIDER=deepseek \
  -e ORBI_PI_MODEL=deepseek-flash \
  -e ORBI_PI_BASE_URL=https://api.deepseek.com \
  -e ORBI_PI_API_KEY="sk-xxx" \
  ghcr.io/orbi-build/orbi:latest

一条 docker run，不需要 compose（runner 是单一服务）。 --cgroupns=host 加 /sys/fs/cgroup 读写 bind 让 systemd 能以 PID 1 身份在容器内运行——默认 private cgroupns 下创建 /init.scope 会失败（已实证；无需 --privileged）。全部状态（orbi checkout、配置、运行时状态、交付 checkout 与 worktree）都在两个 volume 里，容器重建不丢，幂等 setup 在下次启动时重新收敛。

配置如何到达 runner

你提供	到达 runner 的路径
`ORBI_SOURCE_REPO`	任务池仓库。首次启动时 entrypoint 把它克隆进 `/work` volume 并写进生成的 `orbi.toml`。替代方案：bind mount 已有 checkout（`-v ~/projects/myrepo:/work`）——宿主机 uid 需与容器内 `orbi` 用户一致（uid 1000），否则 git 报 dubious ownership。
`GH_TOKEN`	entrypoint 把它写进 `/orbi/.orbi/env`（systemd `EnvironmentFile` 约定，权限 600），每次启动都从注入变量重新生成。tick 时 gh 从那里读取，git 的凭据由 gh credential helper 经 HTTPS 提供——全程无 SSH key；token 绝不进镜像层。它需要对任务池仓库的写权限：classic token 带 `repo` scope，或 fine-grained token 带 Issues、Pull requests、Contents 读写（runner 要用它建 label、分支和 PR）。
`ORBI_PI_PROVIDER`、`ORBI_PI_MODEL`、`ORBI_PI_BASE_URL`、`ORBI_PI_API_KEY`	四个模型 provider 值（要么全设，要么全不设——只设一部分会启动失败并点名缺失的变量）。entrypoint 每次启动都从注入变量重新生成 `/orbi/.orbi/env` 并把 `PI_API_KEY` 写进去——改了 `ORBI_PI_API_KEY`，下次 `docker run`/`docker restart` 即生效，无需手动编辑；`/orbi/.orbi/pi-providers.json`（一个 provider、一个 model，`apiKey` 引用 `$PI_API_KEY`，key 本身不落 JSON）和 `orbi.toml` 里的 `pi_provider`、`pi_model`、`pi_providers` 只在首次启动生成，之后绝不覆盖。
`ORBI_PI_API`、`ORBI_PI_CONTEXT_WINDOW`、`ORBI_PI_MAX_TOKENS`	生成的 `pi-providers.json` 的可选模型上限；默认 `openai-completions`、`128000`、`16384`。
`ORBI_BASE_BRANCH`	可选交付基准分支（默认 `main`）。
`ORBI_ENV_<NAME>`	可选、可重复：透传到 `/orbi/.orbi/env` 为 `<NAME>=<value>`（如 `ORBI_ENV_GROQ_API_KEY` 落地为 `GROQ_API_KEY`），供 provider 文件引用——见下文”进阶：多 provider”。
`orbi-deploy` volume → `/orbi`	deploy home volume：orbi 源码 checkout（`engine_source_track = "release"` 自动跟随最新发布）、生成的 `orbi.toml`、`.orbi/env` 凭据文件与 `.orbi/` 运行时状态。
`orbi-work` volume → `/work`	交付 checkout volume：任务池克隆、`/work/.worktrees/` 下的任务 worktree 与 `/work/.orbi/` 下的 slot 锁。

完整契约——生成的配置、日常操作、故障与修复表——见 3rd/docker/README.md。

第一次交付

runner 跑起来之后，交付一个真实任务：

在任务池仓库开一个 Issue，用两种形状之一陈述一个可观测的运行时结果：修复（when X, should Y, actually Z）或变更（when X, the user should be able to Y; today they cannot because Z）。
打上 ai-ready label（首次启动已创建十二个平台 label）。
跟踪 tick 日志：

docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi \
  journalctl --user -u [email protected] -f

两个 tick 内（timer 每 5 分钟触发一次）Issue 会走完 ai-ready → ai-in-progress → ai-pr-opened 并开出 PR；独立评审一轮后合并（ai-merged）。整条路径不需要任何 docker exec 配置步骤——哪一步需要手工 exec，就是文档或 entrypoint 的缺陷。

Orbi 快速指南

交付所需的基本概念集中在一页；完整参考用链接给出，不在页内重复。

任务长什么样 — 一个 Issue 用两种形状之一陈述一个可观测的运行时结果：修复（when X, should Y, actually Z）或变更（when X, the user should be able to Y; today they cannot because Z），附一小份验收清单：用户旅程按前置条件 → 命令/配置 → 用户看到的成功结果 → 失败路径与修复展开。
label 含义 — ai-ready 是执行开关：runner 只认领带这个 label 的 Issue（认领顺序：p0 优先，其次 bug，再普通 Issue）。被认领后走 ai-in-progress → ai-pr-opened → ai-merged（终态；PR 描述里的 Fixes #N 会自动关闭 Issue）或 ai-fix-needed（下一轮评审修复发现的问题）；ai-blocked（终态）需要人来决策。ai-epic 标记纯协调 Issue，runner 永不认领；ai-release 标记发布任务（见下）。交付状态由 runner 管理；ai-ready、ai-epic、ai-release、 p0、bug 由你来打和摘。
怎么看进度 — 每次运行在 Issue 上只保留一条进度评论，每个里程碑原位更新；tick 日志用上面的 journalctl 命令实时跟踪。
预期结果 — 两个 tick 内出现分支和 PR（描述带 Fixes #N），随后独立评审会话运行（最多 5 轮），合并落在被评审的那个 commit 上——之后 GitHub 自动关闭 Issue。
如何发布 — 发布是独立的 Issue：打 ai-ready + ai-release 两个 label，正文声明 ## Release 块：version、base_branch，以及 scope（#N 列表）或 scope_from_milestone。Runner 的发布状态机冻结 base、等待 CI 全绿、升版本号、打 tag、发布 GitHub Release 并关闭对应 Milestone——全程没有 PR；任何失败停在 ai-blocked，由人决策。

完整参考：Workflow（label、评审循环、发布状态机）与 Operations（可观测性、journal）。

日常操作

命令	用途
`docker logs -f orbi`	setup 结果（`setup=ok` 或 `setup_failed ...`）+ systemd 控制台
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi journalctl --user -u [email protected] -n 50 --no-pager`	tick 日志
`docker exec -u orbi -w /orbi orbi bash -c '~/.local/bin/orbi status'`	队列与当前任务（调试附件）
`docker exec -u orbi -w /orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi bash -c '~/.local/bin/orbi doctor'`	部署体检
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi systemctl --user list-timers`	下次触发时间
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi systemctl --user start [email protected]`	立即触发一个 tick
`docker stop -t 30 orbi && docker rm orbi`	停止并删除（两个 volume 保留全部状态）
`docker volume rm orbi-deploy orbi-work`	彻底清除全部状态

容器内命令一律以 -u orbi 执行（runner 就是以该用户跑的）； systemctl --user / journalctl --user 依赖用户会话总线，docker exec 不会自动带上，需要 -e XDG_RUNTIME_DIR=/run/user/1000。orbi CLI 装在 orbi 用户的 ~/.local/bin，不在 docker exec 的默认 PATH 里——所以套一层 bash -c（docker exec 会为 -u 用户设置 HOME）。升级：docker pull 新 tag 后用同样的 volume 和变量重建容器——状态在 volume 里，entrypoint 与 orbi setup 幂等收敛。

从源码构建

需要改动封装本身（entrypoint、setup oneshot、Dockerfile）时，从仓库 checkout 构建镜像，而不是拉取：

git clone https://github.com/orbi-build/orbi.git
cd orbi
docker build -t orbi-docker 3rd/docker

然后按快速开始同样的 docker run 运行，镜像名换成 orbi-docker。镜像内不含任何凭据——配置按上表在 docker run 时注入。

进阶：多 provider

快速开始从环境变量配置一个 provider。要同时服务多个（如 deepseek 加 groq）：

启动时用 ORBI_ENV_<NAME>（可重复）注入额外的 key： -e ORBI_ENV_GROQ_API_KEY="gsk-xxx" 落进 /orbi/.orbi/env 为 GROQ_API_KEY；
编辑 /orbi/.orbi/pi-providers.json——entrypoint 首次启动生成了单 provider 版本且绝不覆盖已有文件——加入其余 provider，每个 apiKey 引用自己的环境变量（"$GROQ_API_KEY"）；
把 /orbi/orbi.toml 里的 pi_provider / pi_model 指向要用的 provider 与 model，然后重启容器：docker restart orbi（两个文件都是你的——entrypoint 绝不覆盖已有配置）。

首次启动完全没有 provider 变量时不会生成 pi-providers.json； orbi setup 会生成 starter 文件供填写。依赖某个端点前先验证：

docker exec -u orbi orbi bash -c '. /orbi/.orbi/env && pi --provider deepseek \
  --model deepseek-flash --api-key "$PI_API_KEY" \
  --print "reply with the single word: ok"'

返回真实 API 回复即端点与 key 可用；401/超时就是 key 或网络问题。

边界

只做薄封装：不碰 src/orbi/ 核心代码，容器内撞到的阻塞性问题另开核心 Issue。
仅 Linux；不做 compose、多容器编排、镜像自动更新；不进 PyPI 发布包、不进 getting-started 主路径。
社区维护：官方 Issue 优先处理核心 systemd 路径。

从这里开始

核心概念

模型 Provider

配置与运行

参与贡献

参考

发布

Docker（社区维护）

什么时候用它

快速开始

配置如何到达 runner

第一次交付

Orbi 快速指南

日常操作

从源码构建

进阶：多 provider

边界

​什么时候用它

​快速开始

​配置如何到达 runner

​第一次交付

​Orbi 快速指南

​日常操作

​从源码构建

​进阶：多 provider

​边界

什么时候用它

快速开始

配置如何到达 runner

第一次交付

Orbi 快速指南

日常操作

从源码构建

进阶：多 provider

边界