把手工发版产品化：一键部署闭环的工程落地复盘（FastAPI + Paramiko）

1. 背景与痛点在做之前我们的发布主要靠“人肉流程”步骤不一致同一个应用不同人有不同操作习惯缺少证据链失败后只能口述定位成本高不可追溯/不可审计谁发布了什么版本、影响了哪个环境很难查效率瓶颈频繁发布时等待与沟通成本明显目标不是“写个脚本”而是把发布过程做成平台能力可追踪、可观测、可复盘。2. 本次落地的范围与验收标准我们先做 MVP明确验收标准快返回触发部署接口不阻塞立即返回task_id可追踪任务状态至少具备pending/running/success/failed可复盘保存stdout/stderr/exit_code失败原因能还原可扩展后续能平滑演进到实时日志、队列化、回滚、权限体系这类工程很容易“越做越大”所以 MVP 的边界必须清晰先把闭环跑通。3. 总体方案3.1 最小架构调用方前端页面后端FastAPI负责任务创建、状态查询、日志查询执行通道ParamikoSSH 连接 执行命令SFTP 同步作为增强项状态存储MySQL任务与日志落库目标机部署目录中存在统一脚本start.sh3.2 为什么选择 Paramiko start.sh不改现有发布习惯团队已经沉淀了start.sh平台只负责“调度与留痕”最强兼容性SSH 是运维侧最通用的能力不依赖额外 agent工程可控退出码、stdout/stderr 都可采集便于统一判定成功/失败4. 关键设计任务化把发布变成“可管理对象”我们引入deploy_task作为核心抽象任务状态pending → running → success/failed关键证据exit_code stdout stderr error_message关键时间started_at/finished_at后续可以统计耗时、成功率这样做的价值是发布从“临时操作”变成“可查询记录”。5. 执行链路从触发到完成5.1 触发接口只做两件事工程上最关键创建任务并落库pending启动后台执行线程版 MVP / 后续可换队列触发接口不直接执行发布原因很现实HTTP 超时、断链会导致“前端以为失败、实际在跑”没有统一的状态落库点复盘困难5.2 后台执行围绕sh start.sh的标准化步骤后台执行统一遵循下面的“流水线”任务置为running记录started_at读取应用与环境配置目标机、工作目录、认证方式等建立 SSH 连接支持密钥/密码执行cd workdir sh start.sh ...获取 exit_code判定成功/失败的唯一依据采集stdout/stderr入库更新任务状态success/failed写入finished_at与error_message6. Paramiko 实战点6.1 SSH 认证兼容工程优先级优先密钥文件 / 密钥内容兜底密码6.2 远程命令执行的“正确姿势”工程上必须做到三件事拿到退出码不要只看有没有输出采集 stdout/stderr失败排障靠它设置超时避免卡死7. 日志落库策略当前方案stdout/stderr 直接存表。优点实现快、查询简单、对前端友好缺点日志太大可能影响表膨胀与查询性能我们在 MVP 阶段接受这个取舍因为先保证闭环能跑、能复盘等数据量上来再做演进日志分片表 / 对象存储 / 流式推送8. 典型故障与排障清单SSH 连接失败网络/端口/认证不匹配目录问题cd失败、权限不足脚本问题不可执行、换行符、依赖缺失Docker 环境问题daemon 未启动、权限不足、镜像拉取失败“看似成功但不可用”脚本未做健康检查平台只能按 exit_code 判定9. 最终收益标准化发布步骤统一沉淀为平台流程可追溯每次发布都有任务记录与证据链stdout/stderr可复盘失败原因可定位不再靠口述可演进后续扩展实时日志、并发控制、回滚、审批权限成本更低总结把“发布”从动作变成能力回头看这次“一键部署闭环”的落地本质上我们做的并不是再写一套脚本、再堆一层接口而是把原先高度依赖个人经验的“发布动作”抽象成可管理、可追踪、可复盘的“平台能力”。当部署被任务化有状态机、有证据链、有时间线团队协作的边界就被重新定义发布不再靠“谁更熟”而是靠系统把关键步骤标准化把每次执行的输出与结论沉淀下来。更重要的是这个 MVP 的价值不止在于“能一键部署”而在于它为后续演进奠定了统一的工程底座并发互斥、实时日志、队列化执行、回滚与权限审批都可以围绕同一个任务模型平滑扩展。最终我们希望达到的效果是发布成为一条可持续优化的工程流水线而不是每次都需要重新“现场指挥”的临时工程。这样的技术沉淀才是真正能长期降低交付成本、提升稳定性与组织效率的复利。