[Priority: High] [Feature] 支持消费方按需自部署 opencode-a2a-server（参数化拉起）

[liujuanjuan1984]

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

  • 当前仓库已经具备两条可用部署路径：scripts/deploy.sh（systemd 多实例）与 scripts/deploy_light.sh（当前用户轻量托管），但“消费方按需自部署”仍缺少统一、可编排、可验收的交付契约。
  • 结合 README/SECURITY 中已经明确的 single-tenant trust boundary，本需求应收敛为：消费方按参数拉起自己的单租户实例对，而不是在单实例内追求多租户共享。
  • 当前遗留缺口主要集中在：非交互预检、健康验收、参数/secret 组合校验、systemd 资源基线、身份边界与 shell 治理、初始化链路供应链基线，以及未来可选 Docker 路线的评估。

• 🛠️ 详细实施方案 (必须包含涉及的文件路径和核心逻辑/伪代码)

  • 本 issue 作为 umbrella / product-contract issue 保留，不直接承载单一代码提交；后续实施应以子 issue 推进：
    • #148：补齐 scripts/deploy.sh、scripts/deploy_light.sh、scripts/uninstall.sh 的非交互预检、ready 判定、参数校验与机器可读返回契约。
    • #147：补齐 A2A_ENABLE_SESSION_SHELL、session ownership、身份边界与高风险能力治理规则。
    • #149：收敛 scripts/init_system.sh 的 bootstrap 供应链安全基线。
    • #150：补齐 systemd 资源治理、请求体限制与抗滥用基线。
    • #146：仅作为未来可选路线评估 Docker 化，不进入当前主路径。
  • 需要在以下文件形成统一的“单租户自部署契约”说明：
    • README.md
    • SECURITY.md
    • scripts/deploy_readme.md
    • scripts/deploy_light_readme.md
  • 推荐的最小控制流应统一为：

    validate_inputs_and_sudo_mode()
    prepare_instance_root_and_secret_contract()
    start_or_update_single_tenant_instance()
    wait_until_agent_card_and_runtime_ready()
    emit_machine_readable_result(instance_url, agent_card_url, logs_dir)
    

  • 只有当上述子 issue 收敛后，才应考虑是否需要新增更上层的 control-plane / create-status-delete API；当前阶段不引入新的服务控制面。

• 🧪 回归测试建议

  • 部署 smoke：
    • deploy_light.sh start -> status -> stop
    • deploy.sh 首次部署、重复部署、卸载回归
  • 契约回归：
    • 缺失 secret / provider 参数组合错误时，返回稳定错误语义
    • readiness 成功后能稳定访问 Agent Card 与 message:send
  • 安全与治理回归：
    • A2A_ENABLE_SESSION_SHELL=false/true 两种配置的行为边界清晰
    • systemd 资源限制与请求体限制生效且不影响正常调用
  • 文档回归：
    • README / deploy 文档中的路径、命令与脚本实际行为一致

[liujuanjuan1984]

补充记录（需求讨论沉淀）

一、用户提出的关键思路

• “人手动拉起”与“agent 通过 bash 调脚本拉起”本质都可行，后者同样可以满足自动化诉求。
• 现有脚本已支持 uninstall，因此资源卸载也可以由 agent 通过调用脚本完成。
• 当前核心问题不在“是否必须引入新控制面”，而在“现有脚本实现拉起/卸载是否足够妥当、稳健、可编排”。

二、当前脚本实现评估结论

总体结论：可用（MVP），但未达到“妥当完备”。

已具备能力（正向）

1. 敏感参数（token/secret）禁止 CLI 明文传参，降低命令历史泄露风险。
2. systemd 单元具备基础硬化策略（如 NoNewPrivileges / ProtectSystem / UMask）。
3. uninstall.sh 具备 preview-first、确认门槛与误删防护，安全性与可回滚意识较好。

关键缺口（需补齐）

1. 非交互自动化可靠性：deploy 流程缺少与 uninstall 对齐的 sudo -n 预检，agent 非交互执行可能阻塞。
2. 成功语义不充分：启动后主要依赖 systemctl status，缺少“健康探测 + 超时 + 机器可读返回码/状态”。
3. 参数校验不完整：provider/model 与密钥匹配仅部分覆盖（已知 Google/Gemini 较完整，其它 provider 仍有空档）。
4. 约束不对称：uninstall 对 project name 有更严格校验，deploy 侧前置约束未完全对齐。
5. 密钥生命周期治理：当前以 env 文件落盘为主，缺少更细粒度的轮转/最小化暴露策略。
6. 并发幂等边界：缺少同项目部署锁，重试/并发下存在竞态风险。

三、方向共识（当前阶段）

• 先不强制引入新的控制面 API。
• 以“agent 调脚本”作为第一阶段实现路径，优先补齐脚本层稳健性与可编排契约。

四、建议的后续拆解方式（用于下一轮讨论）

• P0：非交互可执行、健康检查与可读状态、关键参数校验闭环。
• P1：并发锁与幂等语义、失败回滚与错误码标准化。
• P2：密钥治理增强、观测与审计完善。

[liujuanjuan1984]

按“可一并修复”原则，已将 systemd 主路径缺口拆分为 4 个子议题，并关联到本主 issue：

分类与子议题

1. 身份边界与高风险能力治理

• [Priority: Low] [Security] 补齐 systemd 模式下 session shell 启用基线与审计治理 #147 [security] 强化 systemd 模式下身份边界与 session shell 治理
• 覆盖缺口：多消费方隔离边界、session shell 风险治理。

2. deploy 自动化契约与输入校验

• [Priority: Med] [Ops] 补齐 deploy 自动化契约：非交互预检、健康验收与参数校验 #148 [ops] 补齐 deploy 自动化契约：非交互预检、健康验收与参数校验
• 覆盖缺口：非交互 sudo 预检、健康探测与机读状态、provider/model/secret 前置校验、EnvironmentFile 安全写入策略。

3. bootstrap 供应链安全

• [Priority: Low] [Security] 加固 init_system 供应链安全基线（脚本安装链路） #149 [security] 加固 init_system 供应链安全基线（脚本安装链路）
• 覆盖缺口：初始化脚本下载与执行链路的供应链风险。

4. 运行时资源治理与请求防护

• [Priority: Low] [Ops] 补齐 systemd 运行时资源治理与请求防护基线 #150 [ops] 补齐 systemd 运行时资源治理与请求防护基线
• 覆盖缺口：systemd 资源/网络约束基线、请求体大小限制与防护。

说明

• 当前仍以 systemd 方案为主路径推进。
• Docker 容器化保持为未来可选路线（见 [Priority: Low] [Ops] 评估 Docker 容器化部署作为未来可选路线（保持 systemd 主路径） #146）。