[security] 收敛 systemd 部署脚本对凭证默认明文落盘的行为

[liujuanjuan1984]

• 🔍 发现的问题 / 原始需求描述

当前 systemd 部署脚本仍会默认把 GH_TOKEN 写入 opencode.env、把 A2A_BEARER_TOKEN 写入 a2a.env、把 provider keys 写入 opencode.secret.env。虽然权限是 600 root:root，但这仍属于长期凭证明文落盘的默认路径。

这会带来几个问题：

• 公开开源仓库会向运维方传递“默认写盘是推荐做法”的错误信号。
• 长期有效 token/key 落盘会扩大误用、备份泄露、主机侧取证暴露的风险面。
• GH_TOKEN / A2A_BEARER_TOKEN 被混入普通 env 文件，也不利于 secret/non-secret 边界清晰化。

相关文件：

• /home/juanjuan/opencode-a2a-serve/scripts/deploy/setup_instance.sh

• /home/juanjuan/opencode-a2a-serve/scripts/deploy/install_units.sh

• /home/juanjuan/opencode-a2a-serve/scripts/deploy.sh

• 🛠️ 建议实施方案

建议采用“默认不持久化，显式 opt-in 才写盘”的路径：

1. 拆分 non-secret 与 secret env files：
   • opencode.env / a2a.env 仅保留非敏感配置
   • opencode.auth.env 单独承载 GH_TOKEN
   • a2a.secret.env 单独承载 A2A_BEARER_TOKEN
   • opencode.secret.env 继续承载 provider keys
2. 新增显式开关，例如 ENABLE_SECRET_PERSISTENCE=true：
   • 未开启时，部署脚本不写入上述 secret files
   • 仅生成 root-only *.example 模板，并要求运维方自行预置 runtime secret files
3. systemd unit 改为加载拆分后的 secret files，而不是把 secret 混在普通 env 文件里。
4. README / deploy 文档更新为两种路径：
   • 默认 secure path：预置 root-only secret files
   • 显式 opt-in path：允许部署脚本代写 secret files，并明确风险

核心逻辑/伪代码：

if ENABLE_SECRET_PERSISTENCE == true:
    write root-only secret env files
else:
    create example templates only
    require operator-provisioned runtime secret files before starting services

验收要求：

• 默认部署流程不再无提示地把长期凭证明文写盘。
• secret / non-secret 文件边界清晰。
• 现有需要持久化的运维场景，仍可通过显式开关完成。

附加快照：

• 发现时代码快照：95e51873f6ed9ba00813d1a214063c3faece272c

[liujuanjuan1984]

补充参考实现：codex-a2a-serve 已在下述 PR 中落地了这一方向，可作为 #163 的实现参考：

• feat: harden logging and deployment security baselines liujuanjuan1984/codex-a2a#31

我建议可以优先借鉴其中这几个点：

1. 默认 secure path 采用“两步部署”
   • 第一次 deploy 只生成目录和 *.example 模板
   • 若缺少真实 runtime secret files，则明确失败退出，不继续启动服务
2. 显式 opt-in 持久化
   • 通过 ENABLE_SECRET_PERSISTENCE=true 明确允许部署脚本把 secret 写入 root-only EnvironmentFile
3. secret / non-secret 配置拆分
   • opencode.env / a2a.env 只保留非敏感配置
   • opencode.auth.env 承载 GH_TOKEN
   • a2a.secret.env 承载 A2A_BEARER_TOKEN
   • opencode.secret.env 承载 provider keys
4. systemd unit 与文档同步收敛
   • unit 只从拆分后的 secret files 读取
   • deploy README / deployment docs 同时说明 secure default path 与 opt-in path

如果 opencode-a2a-serve 后续实施，我建议按“默认不持久化 + 显式 opt-in”的原则推进，而不是只做文件拆分但仍保持默认写盘。

[liujuanjuan1984]

已在分支 issue-163-164-168-deploy-security-docs 完成一版落地，提交：81cb02d3d9da4e3afc7485c7ccb6f8df5f2737d0。

本次围绕 #163 的实际改动：

• deploy.sh 新增 enable_secret_persistence 输入，默认 ENABLE_SECRET_PERSISTENCE=false
• systemd unit 拆分为 opencode.env + opencode.auth.env + opencode.secret.env + a2a.env + a2a.secret.env
• setup_instance.sh 默认只生成 *.example 模板，不再默认把 GH_TOKEN / A2A_BEARER_TOKEN / provider keys 写盘
• 未显式开启持久化时，脚本会要求运维方先补齐 root-only runtime secret files，再允许继续启动服务
• 增加了 EnvironmentFile 单行值校验，避免换行污染写入

同步更新：

• scripts/deploy_readme.md
• README.md
• SECURITY.md
• 回归测试 tests/test_deploy_security_contract.py

验证：

• bash -n scripts/deploy.sh scripts/deploy/setup_instance.sh scripts/deploy/install_units.sh
• uv run pre-commit run --all-files
• uv run pytest

[liujuanjuan1984]

补充一条审查结论：

当前 PR #169 已覆盖 #163 的核心目标，且没有发现需要阻塞合并的问题。

审查结论：

• systemd deploy 默认不再静默把 GH_TOKEN / A2A_BEARER_TOKEN / provider keys 写盘，这一点已经被正面修正
• opencode.env / opencode.auth.env / opencode.secret.env / a2a.env / a2a.secret.env 的拆分是合理的，secret / non-secret 边界更清晰
• setup_instance.sh 在默认模式下改为只生成 *.example 模板，并在继续启动前校验必需 secret files，这比旧行为更稳健
• 本次仍然是 root-only env file 注入方案，不是 secret manager 集成，但对 #163 的关闭标准已经足够

结论：

• #169 合并后，#163 可以关闭
• 无需因当前实现再额外拆出阻塞修复项

关联：

• PR: harden: default systemd deploy to operator-managed secrets #169