harden: default systemd deploy to operator-managed secrets

[liujuanjuan1984]

概要

本 PR 聚焦三类高度相关的改动：

• 收敛 systemd deploy 对长期凭证默认明文落盘的行为
• 补齐公开仓库安全边界与披露说明
• 更新 README 首页架构入口，并明确推荐 a2a-client-hub 作为客户端消费层

模块一：systemd deploy secret handling

对应：#163

本次将 systemd deploy 的 secret handling 调整为“默认由运维方预置 root-only runtime secret files，显式 opt-in 才允许 deploy 代写” ：

• scripts/deploy.sh
  • 新增 enable_secret_persistence 输入
  • 默认 ENABLE_SECRET_PERSISTENCE=false
  • 不再默认要求通过环境变量提供 GH_TOKEN / A2A_BEARER_TOKEN
• scripts/deploy/install_units.sh
  • unit 改为拆分加载：
    • opencode.env
    • opencode.auth.env
    • opencode.secret.env
    • a2a.env
    • a2a.secret.env
• scripts/deploy/setup_instance.sh
  • 默认只生成 *.example 模板
  • 未显式开启持久化时，不再默认把 GH_TOKEN / A2A_BEARER_TOKEN / provider keys 写盘
  • 启动前会强制校验必需的 runtime secret files 是否存在且包含对应 key
  • 增加 EnvironmentFile 单行值校验，降低换行污染写入风险

模块二：安全策略文档

对应：#164

• 新增根目录 SECURITY.md
• 集中说明：
  • A2A_BEARER_TOKEN 的边界
  • OpenCode + opencode-a2a-serve 的 single-tenant trust boundary
  • payload logging 风险
  • provider key 风险边界
  • systemd secret persistence 策略
  • 漏洞披露建议与受支持分支策略
• README.md、scripts/README.md、scripts/deploy_readme.md 已同步增加导航，避免安全说明继续分散

模块三：README 首页与客户端推荐

对应：#168

• README.md 首页新增 Mermaid 架构图
• 明确推荐 a2a-client-hub 作为客户端侧消费层
• README 结构调整为：定位、能力、设计原则、架构图、安全模型、文档导航
• 强调本仓库聚焦服务端 / runtime boundary，而客户端消费集成应下沉到 a2a-client-hub

测试与验证

• 新增 tests/test_deploy_security_contract.py
  • 覆盖 deploy secret handling 默认行为
  • 覆盖 unit secret/non-secret env file 拆分
  • 覆盖 README / SECURITY / deploy guide 的关键契约断言
• 已通过：
  • 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

实施评估

这次没有照抄 /home/juanjuan/codex-a2a-serve，但参考了两类思路：

• README 首页信息分层与消费端入口表达方式
• systemd deploy 的 secret persistence 默认关闭、显式 opt-in 的契约设计

当前改动保持了现有 systemd 主路径和双进程架构，没有扩大到 #148 / #147 / #150 的完整治理范围。
其中：

• #148 仅部分前进：本 PR 增加了 EnvironmentFile 单行值校验，但未覆盖非交互预检、readiness/timeout、完整参数校验契约

Closes #163
Closes #164
Closes #168
Relates to #148
Relates to #165