Symphony 部署与维护

文档状态: draft
文档 Owner: DOC
事实源: canonical-docs
更新: 2026/10/16

先确认所维护的服务、版本、有效 WORKFLOW、来源范围与 host owner。Plane 发布和文档站部署各自从部署排障选择；本页不把它们的发布命令当作 Symphony 服务管理方式。

选择维护路径

对象	可复用的内容	须向 owner 确认
独立官方 Elixir 参考实例	首次运行中的固定源码、依赖、配置与启动参数	目标宿主、现有认证、目录、来源范围、端口与进程管理
团队可复用 Docker 镜像	独立实例步骤	镜像可用性、CPU 架构、独立配置、认证、数据卷和领取范围
团队受管实例	团队实施说明与固定 Code Map	实际 deployed revision、扩展版本、可信 live 配置和进程外交付方式

除下面单独标明的团队 Docker 方案外，本页 CLI 命令和默认行为只按官方 be10a1b79df723d6d7612b5651c8522704dafb2e 核对。本文未安装、启动、升级或运行目标实例；没有通用 systemctl / launchctl / Docker 服务名可供照抄，不猜造私有部署路径。

复用 Docker 镜像，启动独立项目实例

这是团队 Symphony/Codex 镜像的部署方法，适用于已经能取得该镜像的宿主。它不是官方上游提供的通用 Docker 发行版。下面以 Mac Docker Desktop 上新增 project-b 为例；名称、目录、端口均为示例，需要替换为目标项目值。阅读或发布本文不会创建实例、派发任务，也不会调整现有实例或通知服务。

1. 确定镜像和项目输入

可复用基线为 autodev/symphony:f2abf4bab59160ac578275993d8593b3cd2a1fdb，架构为 Linux ARM64。该交付将镜像保存在原宿主的 Docker Desktop，未发布到镜像仓库；这个标签不是可供任意机器直接 docker pull 的公共地址。同一 Docker daemon 可复用已有镜像；其他宿主先通过受控镜像分发取得相同版本，AMD64 机器须另外提供经外部 CI 构建和验证的对应产物，不能推定已有多架构支持。

镜像包含 Symphony 引擎、团队扩展、Codex、Git、Python、Node 和 GitLab 交付辅助工具；项目的 tracker、仓库、提示词和凭据从外部提供。它不包含任意项目 SDK，也不提供 Mac GUI、Unity Editor 或宿主钥匙串。依赖这些能力的项目须先明确外部执行方式，不能把容器启动当作能力迁移完成。

开始准备前确定：

任务来源：适配器及版本、项目身份、活跃/终态、实际领取条件。Plane 与 Linear 的字段和委托合同分别沿任务来源核对。
交付目标：仓库地址、默认分支、提交身份、MR/PR、外部 CI、合并与发布要求。
实例资源：独立实例名、尚未占用的宿主端口、独立配置/凭据目录和独立持久卷。
执行能力：模型与认证、项目工具链、容器访问 tracker/Git/CI 的网络路径。容器内 localhost 指容器自己，宿主服务应使用在目标 Docker 环境中可达的地址。

启动即开始调度，可能立即领取符合条件的任务。必须先确定目标项目的执行授权与领取范围；只准备环境时，不给新实例配置可领取的真实任务。不能让两个实例消费同一个任务范围。

2. 准备实例目录和 Compose

一个实例使用一套目录；不要复制现有实例的数据卷、会话或全部 secrets/。目录形态：

symphony-project-b-docker/
├── compose.yaml
├── .env
├── config/
│   ├── WORKFLOW.md
│   ├── codex.toml
│   ├── AGENTS.md
│   └── gitconfig
└── secrets/
    ├── runtime.env
    ├── codex-auth.json
    ├── gitlab.env        # 使用镜像内 GitLab helper 时按其约定提供
    └── git-credentials   # 使用下述 Git store helper 时提供

从拥有访问权限的 autoai/autodev-trial 源码 checkout 取得 symphony/container/compose.yaml；本页固定参考 owner revision 58d6290908b735939d7c8ece9df91d9a925e88e8。compose.yaml 是通用入口，trial.py、symphony-deploy-trial 和 trial 的 agent.sh 是 trial 专用控制入口，不能拿来部署新项目。

以下命令用于日后明确执行接入时，先填写真实路径；本文未执行：

umask 077
# 示例绝对路径；替换 operator 和来源 checkout 路径。
INSTANCE_ROOT=/Users/operator/Services/symphony-project-b-docker
SOURCE_ROOT=/absolute/path/to/reviewed-autodev-trial-checkout
mkdir -p "$INSTANCE_ROOT/config" "$INSTANCE_ROOT/secrets"
cp "$SOURCE_ROOT/symphony/container/compose.yaml" "$INSTANCE_ROOT/compose.yaml"

在 .env 中填写七项必需变量，目录使用真实绝对路径，不存放 token：

SYMPHONY_IMAGE=autodev/symphony:f2abf4bab59160ac578275993d8593b3cd2a1fdb
SYMPHONY_INSTANCE=project-b
SYMPHONY_STATE_DIR=/var/lib/symphony/project-b
SYMPHONY_STATE_VOLUME=symphony-project-b-state
SYMPHONY_HOST_PORT=18768
SYMPHONY_CONFIG_ROOT=/Users/operator/Services/symphony-project-b-docker/config
SYMPHONY_SECRET_ROOT=/Users/operator/Services/symphony-project-b-docker/secrets

Compose project 和容器名均为 symphony-project-b。18768 只是示例，未确认空闲。配置与凭据目录分别只读挂载至 /run/symphony 和 /run/secrets；持久卷挂载到 SYMPHONY_STATE_DIR。宿主端口只绑定 127.0.0.1，不自动向局域网公开。

3. 填写四份必需配置

文件	必须按新项目填写的内容
`WORKFLOW.md`	tracker/provider/project、状态、hooks 中的 clone URL 与默认分支、并发、执行命令，以及 Markdown 正文中的仓库、工具、交付与验收约束
`codex.toml`	模型/provider、文件认证存储、执行策略；只配置该实例需要的能力
`AGENTS.md`	实例指导、项目边界与交付责任；仓库自身的指导仍由仓库拥有
`gitconfig`	提交身份、credential helper 与 Git URL 的认证匹配策略

examples/trial/WORKFLOW.md 仅为参考文件，没有自动同步或 fallback。不能只改 YAML 的项目 ID：正文和 hook 仍可能指向 trial。切换 Plane/Linear 也不能只改 tracker.kind，须使用相应适配器的完整配置。

在完整 WORKFLOW 中保留以下容器布局；这是字段片段，不是可独立启动的完整 WORKFLOW：

workspace:
  root: $SYMPHONY_WORKSPACES
agent:
  max_concurrent_agents: 1
server:
  host: "0.0.0.0"
  port: 8768

容器内固定监听 8768；新实例通过不同的宿主端口映射，不能只把 WORKFLOW 改成 18768。Backlog 和独立审核是否启用按该项目既有授权确定，不从 trial 示例推导新项目授权。

本团队当前 codex.toml 的执行/认证基础配置如下；具体模型与 provider 仍须符合实际账号和项目选择：

sandbox_mode = "danger-full-access"
approval_policy = "never"
cli_auth_credentials_store = "file"
model_provider = "openai"

WORKFLOW 的 codex 配置也须与该执行策略一致。需要环境变量传给 Codex app-server 时，使用镜像基线已采用的 codex --config shell_environment_policy.inherit=all app-server，并确认运行环境只提供该项目需要的变量。

若使用文件型 Git 凭据，gitconfig 可采用以下片段；另行填写提交身份：

[credential]
    helper =
    helper = store --file=/run/secrets/git-credentials
    useHttpPath = true

4. 准备认证，保留状态边界

secrets/runtime.env 必须存在，Compose 从这里载入 WORKFLOW 所引用的环境变量。Plane 示例需要 PLANE_API_KEY，其他 provider 按相应合同提供；文件只含该实例实际使用的变量。
首次启动空卷时，secrets/codex-auth.json 必须提供，由已授权的 Codex 认证取得。它只是首次认证种子：持久卷已经有 codex/auth.json 后，修改种子不会切换账号或覆盖刷新后的认证。
Git clone/push 与 provider API 是不同认证用途。按选择的 Git helper 提供 git-credentials；若工作流使用内置 GitLab helper，则按 helper 约定提供 /run/secrets/gitlab.env。GitHub 项目须准备自己的 API 工具与认证，不能沿用 trial 的 GitLab 目标。
凭据不写入镜像、WORKFLOW、公开 .env、提交或交付材料；即使复用同一已授权账号，新实例仍使用独立数据卷。保留私有文件的受限读取权限。

启动器把 codex.toml、AGENTS.md、gitconfig 复制到该卷内的有效 HOME，WORKFLOW 则直接读取挂载文件。认证、Codex 会话、工作目录、执行记录和日志保存在该实例状态目录中；更新配置或重建容器时保持卷名和容器内状态路径不变。

5. 创建独立卷并启动

Compose 将状态卷声明为 external: true，首次部署必须先创建该实例的卷。以下仍为 Mac Docker Desktop 示例，$HOME 必须是拥有该 Docker daemon 的宿主账号；在 Linux 或其他 Docker 环境中使用其明确配置的 endpoint：

DOCKER_BIN=/Applications/Docker.app/Contents/Resources/bin/docker
DOCKER_ENDPOINT="unix://$HOME/.docker/run/docker.sock"
"$DOCKER_BIN" --host "$DOCKER_ENDPOINT" volume create symphony-project-b-state

cd "$INSTANCE_ROOT"
"$DOCKER_BIN" --host "$DOCKER_ENDPOINT" \
  compose --env-file .env --file compose.yaml \
  up --detach --no-build worker

执行 shell 不应导出 SYMPHONY_* 或 COMPOSE_* 覆盖值，它们可能优先于 .env。不切换全局 Docker context，也不运行 trial 的部署 job。命令只指定新实例的 Compose 文件与 worker，现有实例和通知服务不在操作范围内。

启动后从新实例的 http://127.0.0.1:18768/api/v1/state 观察新鲜快照、实例任务与来源访问，按运行观察解释错误。Compose 启动成功不等于 tracker 可用，也不等于编码、MR/PR、外部 CI 和合并的完整链路已验证。真实任务闭环须在用户明确授权的任务范围内另行记录证据，不能自动建单。

新实例不会自动加入通知服务或聚合总览；需要接入时另行确定消费者配置。本文不修改这些服务。

6. 日常改配置与恢复

日常模型、提示词或轮询参数直接修改该实例的文件，不经 CI 修改项目配置，也不用重建镜像。先从运行 API 确认没有正在执行或重试的任务，等待已有任务完成；stop 会中断进程，不是排空操作。保持相同的 INSTANCE_ROOT、DOCKER_BIN 和 DOCKER_ENDPOINT：

cd "$INSTANCE_ROOT"
"$DOCKER_BIN" --host "$DOCKER_ENDPOINT" \
  compose --env-file .env --file compose.yaml stop worker

# 私下备份要改的文件，再编辑 config/ 或所需 secrets/。
# 先停止再保存：运行中的 Symphony 可能读取挂载的 WORKFLOW。

"$DOCKER_BIN" --host "$DOCKER_ENDPOINT" \
  compose --env-file .env --file compose.yaml \
  up --detach --no-build --force-recreate worker

重建容器使环境变量和启动时复制的配置一起生效，并保留独立卷中的认证与会话。配置错误时停止该 worker、恢复备份文件，再用同一命令启动；不要通过删除状态卷来修复配置。更换项目身份、账号、卷、目录或端口是实例迁移，应单独评估现有任务、状态和消费者，不当作普通参数修改。

镜像、启动器和 Compose 源码变更仍须源码审阅与精确 head 的外部 CI；上述命令是 host owner 的配置运维步骤，不允许 worker 自行重启其宿主。文档构建通过只证明文档交付，不证明新增项目已部署或跑通。

固定来源与证据边界

本节按团队 autoai/autodev-trial 的以下固定来源核对，原仓库访问权限仍由 owning surface 管理：

来源 revision	Locator	支撑内容
`f2abf4bab59160ac578275993d8593b3cd2a1fdb`	`symphony/container/Dockerfile`、`entrypoint.py`、`compose.yaml`	镜像内容、启动输入、认证种子与卷布局
`58d6290908b735939d7c8ece9df91d9a925e88e8`	`symphony/container/README.md`、`compose.yaml`、`trial.py`、`examples/trial/WORKFLOW.md`	固定文件配置、通用 Compose 与 trial 专用 owner 的边界

owner 源码 revision 与镜像源码 revision 不必相同，配置方案的交付没有重建上述镜像。本页只同步可复用步骤；不公开凭据、真实项目 ID、宿主私有路径或一次性执行日志，不声称其他项目已经完成实例切换或真实任务验证。

启动前后

完整准备复用首次运行；维护时额外确认同一来源范围没有重复实例、现有任务与目录已识别、配置和凭据由正确的 host 进程读取。不要把 WORKFLOW 的磁盘新内容或服务进程存在单独当成健康证明。

该固定 CLI 支持明确 workflow 路径、--port、--logs-root，并强制要求工程预览确认参数。已有二进制和合法配置就绪后，POSIX shell 的参考启动形态为：

mise exec -- ./bin/symphony \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails \
  --port 4000 \
  --logs-root ./operator-observation \
  ./FIRST-RUN-WORKFLOW.md

这是独立官方 checkout 的参数示例，文件、目录和端口须匹配实际环境；不是团队受管服务的重启命令。参数依据为固定 CLI，与工程预览及未实跑限制一起阅读。

配置与重载

配置字段分层见配置与扩展边界，来源专属字段见任务来源。确认运行进程真正读取的文件、环境与版本，再判断设置是否生效。

固定官方版本的无效运行时重载保留最近一次有效配置；正在运行的 Agent 不保证自动重启，HTTP listener 设置也不保证热重绑定。团队审核写操作对 live-host WORKFLOW 的 fail-closed 校验另有合同，不能以核心 last-known-good 机制代替。

日志在哪里

固定 LogFile在日志根下拼接 log/symphony.log。缺省日志根取进程工作目录；上面的 --logs-root ./operator-observation 因此对应其下的 log/symphony.log 路径，而不是直接写到日志根文件。

日志采用 OTP 轮转处理；默认上限为单文件约 10 MiB、5 个文件，可受应用配置影响。轮转产生的实际文件以宿主目录为准。配置成功后默认 console handler 会被移除，因此启动终端没有持续业务日志不能单独证明没有执行。

围绕 issue 标识、会话、时间、最近事件、hook 或来源错误读取必要片段。不要把完整日志、凭据、私人截图或私有路径复制到长期站点；维护任务只保存适当受控引用。

观察服务与任务

该版本的 HTTP 服务按 server.port 或 CLI --port 启用；schema 的 host 默认是 127.0.0.1。它是可选观测面，不是一个已经具备生产认证、网络隔离与 hardening 的通用管理平台。

读取 /api/v1/state 和 /api/v1/<issue_identifier> 时同时检查响应内容、生成时间和任务身份。HTTP 200 仍可能带 snapshot 错误；issue 404 不等于任务不存在。具体只读命令与解释复用任务故障处理，不要另写一套状态合同。API 与页面依据为固定 HttpServer和 Router。

升级与恢复顺序

固定身份。 记录当前安装 revision / 二进制、有效配置身份、来源范围及需要保留的任务和目录；原始资料留在 owning 系统。
明确变化。 比较目标 revision 的配置、适配器、工具与扩展兼容，不把新的官方能力自动视为团队已启用。
完成源码检查。 在 owning 外部 CI 对精确 head 执行已有检查；文档仓本地禁令不变。
由进程外 owner 切换。 按其受审交付和停止方式操作，先确认旧执行及外部副作用，不创建第二个领取同一范围的实例。
读回结果。 核对实际二进制 / 版本、有效 WORKFLOW、来源访问与新实例快照；按已授权任务确认需要的运行闭环，不能只看安装脚本退出成功。

失败时按 owning 流程恢复到已知版本与相容配置；不要直接删除锁、目录或业务状态来制造空闲。内存阻塞记录会在重启后丢失，活跃任务可能再次入选；终态又可能清理目录。恢复细节引用失败与恢复，尤其检查残留进程、目录成果与重复外部写入。

完成判据

服务版本、配置与来源范围一致，预期观察入口有效，已授权任务的运行与结果有证据，残留风险和未完成项明确。源码、CI、安装、服务健康和业务验收分别记录；任何一项不能替代其他项。本文没有实施权限、凭据、费用或运行产品配置变更。

选择维护路径​

复用 Docker 镜像，启动独立项目实例​

1. 确定镜像和项目输入​

2. 准备实例目录和 Compose​

3. 填写四份必需配置​

4. 准备认证，保留状态边界​

5. 创建独立卷并启动​

6. 日常改配置与恢复​

固定来源与证据边界​

启动前后​

配置与重载​

日志在哪里​

观察服务与任务​

升级与恢复顺序​

完成判据​