没有不值得去解决的问题,也没有不值得去学习的技术!

A Tour of Go 多语言翻译项目:从一次 203/EXEC 故障到生产自动部署脚本落地

图 3:生产自动部署脚本第一次真实运行时,systemd 已经显示 active,但首次 localhost 探测仍然得到 HTTP 000;随后连续 3 次同时满足 active + HTTP 200 后,脚本才判定部署成功,并继续完成公网 HTTP 200 验收。这次真实运行验证了连续应用层健康检查的必要性。

作者:

在

Go 学习与文档多语言本地化项目

图3:访问过去的 Go Tour 简体中文站 tour.go-zh.org 时,当前已经无法正常建立连接。

(1) 从「A Tour of Go 中文版」这个搜索词开始:我决定做一个持续维护的 Go Tour 中文版

本地运行的 A Tour of Go「Methods continued」课程页面,左侧为课程说明,右侧为 Go 代码编辑器及运行结果。

(2) A Tour of Go 中文版项目设计冻结:从 101 页到 103 页,从 Gin 转向 Cobra CLI

A Tour of Go 中文版开发实战:英文基线、在线运行与 101 页上游同步体系

(3) A Tour of Go 中文版开发实战:英文基线、在线运行与 101 页上游同步体系

go-tour-i18n 项目完成首个简体中文课程页面 welcome/1 的整页翻译、结构校验和本地预览。

(4) A Tour of Go 多语言翻译项目实录:完成首个 zh-CN 页面翻译闭环

图 1:DeepSeek 官方更新日志显示,本次只更新 DeepSeek-V4-Flash,DeepSeek-V4-Pro API 与 APP、Web 模型均未更新

(5) A Tour of Go 中文翻译项目进展:完成前 8 页、修复 present 语法,并暂缓 DeepSeek 对比

图 1:generics/1 简体中文页面本地预览

(6) 一个页面重试五次:使用 GLM-5.2 翻译 A Tour of Go 时遇到的 Token 与 Present 结构问题

图 1:methods/16 简体中文页面浏览器预览

(7) A Tour of Go 中文翻译实录:如何只翻译教学代码注释,而不破坏 Go 代码

图 2:A Tour of Go methods/20「练习:错误」中文候选页面最终渲染效果

(8) A Tour of Go 多语言翻译:当正确的中文语序被受保护标记顺序校验误判

图 3:methods/24 中文页面,静态代码、Bounds 行内代码和链接内的 image.Rectangle 均正确渲染

(9) A Tour of Go 中文翻译完成 7 个代表页校准:最后 3 页又发现了哪些真实问题

图 2:首批 10 个普通页面经过试跑与流程校准后全部进入 ready

(10) A Tour of Go 多语言翻译项目:首批 10 个普通页面试跑,从 2 个 blocked 到全部 ready

图 2:flowcontrol/6 最终中文页面,return 与 v 为适应自然中文语序发生整体换位

(11) A Tour of Go 中文翻译第二批实跑:从 Inline Code 顺序误判到历史响应重新验证

图 1:flowcontrol/6 首次原始输入实验直接通过统一自动校验

(12) A Tour of Go 多语言翻译项目:从 swap 问题重新审视 Token 保护,原始输入与最小保护的一次真实实验

图 7:moretypes/1 最终中文页面预览。左侧课程正文、静态代码块、行内代码和教学注释均正常渲染,右侧官方 Go 示例继续保持原样。

(13) A Tour of Go 多语言翻译实战:第三批 10 页全部 Ready,继续校准 Protected Token 的结构角色

图 4:上游源码确认共有 103 个课程页面,zh-CN 最终达到 ready=103、pending=0、blocked=0

(14) A Tour of Go 多语言翻译项目:zh-CN 103 个课程页面全部 ready,课程正文翻译阶段完成

图 4:GitHub 与 ChatGPT 已成功连接

(15) ChatGPT 连接 GitHub 实测:让 AI 直接读取 go-tour-i18n 仓库参与译文审核

图 3:中文 Go 术语校准完成后,将确定的译法写入 zh-CN glossary

(16) 为什么 channel 最终选择“通道”:A Tour of Go 中文术语统一的一次实践

图 1:技术含义基本正确,但“返回一个返回……”已经明显影响阅读,因此仍被列入 C 类修订

(17) 103 页逐页审核后,只返修 16 页:A Tour of Go 中文正文发布前质量审计

图 2:中文课程页面以及已经完成本地化的编辑器控制区

(18) A Tour of Go 多语言翻译项目:公共 UI 本地化完成,从课程译文走向完整中文界面

图 2:完整 zh-CN 正式投影成功生成,103 个课程页面被重新组装为 7 个 .article

(19) 从 103/103 ready 到完整站点验收:A Tour of Go 中文版补齐正式投影与课程元数据本地化

图 3:从 production bundle 独立启动的 A Tour of Go 简体中文页面,课程正文、公共 UI 和官方 Go 示例均已进入最终发布形态。

(20) A Tour of Go 多语言翻译项目:103 页全部完成后,我终于生成了可独立部署的 zh-CN Production Bundle

图 1:A Tour of Go 简体中文版正式生产页面,远程运行已经成功输出“Hello, 世界”。

(21) A Tour of Go 多语言翻译项目:zh-CN 正式上线,从生产发布到 go.dev Playground 的完整部署记录

图 1:新生产域名 go-dev.shuijingwanwq.com 已正常访问,Go 示例远程运行成功

(22) A Tour of Go 多语言翻译项目:从 go-tour 到 go-dev,完成 EdgeOne、Nginx 与 HTTPS 生产域名迁移

图 1:A Tour of Go 多语言翻译项目正式生产首页

(23) A Tour of Go 多语言翻译项目正式上线:从项目首页、公共 Footer 到生产发布元数据的完整收尾

图 3:GA4 g/collect 请求返回 HTTP 204,并携带当前课程页面地址,确认 Google Analytics 已产生真实事件上报

(24) A Tour of Go 多语言翻译项目:接入 Google Analytics 与百度统计,从 systemd 注入到 EdgeOne 与真实上报验证

图 1:生产环境 robots.txt 与 sitemap.xml 已正确对外提供,Sitemap 共包含 104 个规范 URL。

(25) A Tour of Go 中文站上线后:补齐 robots.txt、Sitemap,并完成五大搜索引擎提交

图 4:发布生产并刷新 EdgeOne 缓存后,再次通过真实手机访问,顶栏项目名称已经完整保持在一行,最终移动端验收通过。

(26) A Tour of Go 多语言翻译项目:修复手机端首页顶栏标题换行,并完成真机验证

图 3:生产自动部署脚本第一次真实运行时,systemd 已经显示 active,但首次 localhost 探测仍然得到 HTTP 000;随后连续 3 次同时满足 active + HTTP 200 后,脚本才判定部署成功,并继续完成公网 HTTP 200 验收。这次真实运行验证了连续应用层健康检查的必要性。

(27) A Tour of Go 多语言翻译项目:从一次 203/EXEC 故障到生产自动部署脚本落地

图 1:阿里云生产环境访问 go.dev Playground 时出现 TLS 握手超时

(28) A Tour of Go 多语言翻译项目:为 Playground 搭建独立的 ZgoCloud 执行代理

图 3:清除 /tour/script.js 缓存后,Run 已直接请求 ZgoCloud /compile 并返回 HTTP 200

(29) A Tour of Go 多语言翻译项目:将生产 Run / Format 切换到 ZgoCloud 执行节点

【图 1:微信中运行 Go 示例时出现 Error communicating with remote server.】

(30) A Tour of Go 中文版手机端运行与格式化偶发失败排查:从间歇性报错到补强 Nginx 可观测性

【图 4:向 golang-dev 公开邮件列表发送 Playground 使用告知邮件并投递成功】

(31) A Tour of Go 多语言项目:为 Playground 代理增加唯一 User-Agent,并主动告知 Go 官方

【图 3:百度剩余 9 个核心 URL 提交成功,remain 归零】

(32) A Tour of Go 搜索引擎收录实测:从 Google 自然索引到百度主动提交与 Bing IndexNow

【图 1:当前正式中文 methods/24 页面,右侧示例代码运行成功】

(33) A Tour of Go 中文翻译完成后,我为什么重新评估 minimal-protect 翻译模式

【图 3:5 个页面 Request SHA256 完全一致,但 Response SHA256 全部不同】

(34) A Tour of Go 翻译实验:更多原始上下文为什么没有更好?从 157 个保护标记到 30 次重复盲评

图 3:3 个代表页 × 4 个评审模型,共 12 次匿名评审的完整排名与第一名票数。

(35) A Tour of Go 翻译质量再评估:minimal-protect 未达预期后,我开始比较 ChatGPT、Codex 与 GLM-5.2

图 2:GitHub 中的 chatgpt-zh-CN-008 重译批次。一个 Batch 同时保存 inputs、raw-responses、candidates、validation 和 retry 记录,GitHub 成为 ChatGPT 与本地翻译流水线之间的数据交接层。

(36) 没有 OpenAI API,我如何用 ChatGPT + GitHub 完成 A Tour of Go 103 页全量重译

图 1:103 个正式课程页面完成最终语义质量审核,结果为 A=103、B/C/D=0,同时不存在缺失、重复或额外页面。A/B/C/D 是本轮项目内部语义质量分级,并不是自动结构 validator 的结果。

(37) 103 页翻完还不能发布:A Tour of Go ChatGPT 译文的语义审核与 Canonical Promotion

图 3:7 个 article endpoint 的 production origin 与 EdgeOne 公网响应全部 exact match,同时新的 ChatGPT 译文标记存在,旧版译文标记已经消失。

(38) 103/103 与 7/7 Exact Match:A Tour of Go ChatGPT 新译文的最终线上验收

【图 2:upstream source preview】

(39) A Tour of Go 多语言翻译项目首次实现 upstream 同步机制:从一次性翻译到长期维护

图 2:A/B/C/D 质量评级规则,展示正式质量 rubric 与 Promotion gate。

(40) A Tour of Go 多语言翻译项目引入 Translation Quality Review:从自动验证到 AI 翻译质量控制

图 4:翻译后 Playground Example,展示中文注释与保持不变的 Go 代码结构。

(41) A Tour of Go 多语言翻译项目实现 Playground Example 本地化:从代码注释翻译到完整学习体验

图 5:公网页面验证广告脚本输出

(42) A Tour of Go 多语言翻译项目接入广告系统:从 AdSense 专用配置到通用 HTML 注入架构

图 3:百度统计单页应用设置

(43) go-dev 单页网站接入统计与 Google AdSense Auto Ads 验证记录

图 1:GitHub 仓库中的多语言翻译项目结构

(44) A Tour of Go 多语言翻译项目:选择日语作为第二语言并启动翻译验证

图 5:模型身份描述不一致

(45) A Tour of Go 多语言翻译项目中的 AI 协作异常排查:一次长期工程会话失效分析

【图 1:ChatGPT GitHub 写入流程调整说明截图】

(46) go-tour-i18n 翻译流程调整:从 ChatGPT GitHub 写入到本地 artifact 导入

图 4 展示了本次异常状态。

(47) go-tour-i18n 翻译自动化流程复盘:已验证的 ChatGPT 翻译能力在新任务中的稳定性问题

【图 6:全部评审结束以后才读取 secret key,完成最终揭盲】

(48) A Tour of Go 翻译质量再评估:Codex High 已接近 ChatGPT High,我决定调整默认翻译引擎

图 4:ja-JP 生产课程页实际运行 Go 示例

(49) A Tour of Go 日语版正式上线:第二门语言 ja-JP 完成生产发布

图 1:ja-JP 上线以后,先提交“新增语言标准化流程”

(50) A Tour of Go 多语言扩展复盘:为第三门语言建立标准化流程

图 1:课程正文结束以后,页面左侧仍然存在大块视觉空白,但 AdSense 并没有在这里插入展示广告。

(51) A Tour of Go 明明有大片空白,为什么 AdSense 就是不显示展示广告?

图 2:golang/website 当前的 _content/tour/。课程内容、静态资源和模板都在这个上游目录中持续维护。

(52) 为了 AdSense,要不要放弃 SPA?A Tour of Go 页面架构的一次取舍

图 4:最终的手动课程广告真实展示在课程内容区域内,而不是 footer 之后。

(53) 保留 SPA 以后,广告应该放在哪里?从 AdSense 预览到方案 B

图 1:Google Search Console 中,多个不同的 A Tour of Go 课程 URL 被判断为“重复网页,用户未选定规范网页”。

(54) SPA 的 SEO 老问题:为什么最后还是给 103 个 A Tour of Go 课程页生成了 Prerender HTML

图 2:方案 B 生产环境中,源码已经正常,但课程主体高度异常缩短,footer 提前进入第一屏。

(55) 从源码空白到 AdSense 高度污染:A Tour of Go 方案 B 的生产收尾

图 1:A Tour of Go 德语版 de-DE 已正式运行在生产环境

(56) A Tour of Go de-DE 上线复盘:第三门语言用了约 16 小时,下一门如何压到 8 小时?

图 1:fr-FR 首次 production 验收完成后,我没有立即开始 ko-KR,而是先连续完成新增语言与首次生产流程的优化

(57) 法语版上线后,我没有马上开始韩语:A Tour of Go 新增语言流程的一轮完善与简化

图 1:根据 ko-KR 期间 76 次 Git 提交估算实际工作时间

(58) 原本预计 6 小时,最后用了约 16~18 小时:A Tour of Go 韩语版上线复盘

图 2:英文 source 与当时发生 validation failure 的 ko-KR candidate 对比

(59) Validator 报错,到底该改译文还是改规则?一次 A Tour of Go 韩语翻译实战

图 2:法语 A Tour of Go 仓库目前已经归档,页面仍保留 553 Commits 和 61 Contributors 的历史

(60) 从法语 553 次提交到韩语两代离线:A Tour of Go 社区翻译为什么难以长期维护

【图 4:es-ES 首次 Production 收口后连续完成的流程优化 commit】

(61) 从 es-ES 首次上线复盘:我把 A Tour of Go 新增语言的 Production 流程又收敛了一轮

图 1:旧公网验收链路连续出现 curl 28 超时,最终导致 public-machine 阶段失败

(62) A Tour of Go Production 公网验收踩坑:从跨境 SOCKS 链路改为 zgocloud direct

图 1:两次 Production Machine Acceptance 都已经通过,但 Headless Chrome 分别在 / 和 /tour/ 判定页面没有完成渲染

(63) 页面明明能打开,为什么 Headless Chrome 仍然判定 Production 失败?

图 3:Bing 从 Google Search Console 中识别到新的 it-IT 站点,并同时发现已有的 1 个 sitemap

(64) GSC → Bing Webmaster Tools:多语言站点如何减少重复验证

图 3:英文站 3 小时内出现 565 个 Cloudflare 来源 URL

(65) IndexNow 实战:手工提交长期不显示,Cloudflare Crawler Hints 却很快出现在 Bing Webmaster Tools

【图 1:A Tour of Go 项目首页目前的语言版本列表】

(66) 从 nl-NL 到 tr-TR:A Tour of Go 连续上线三门语言后,我又优化了哪些流程

【图 4:Go local 页面中已经出现 French、German、Korean、Simplified Chinese】

(67) 从邮件无人回复到进入 Go 官方 Go local:我的 4 个 A Tour of Go 翻译站终于被收录

图8:最终只保留一把启用的新 API Key

(68) 腾讯云 EdgeOne API 自动化:从 CAM 子用户到最小权限 API Key 的完整配置

【图 7:Production Release Batch 最终汇总】

(69) 从同步 Go 官方上游到一个命令发布 10 个语言站:A Tour of Go Production 流程的再次收敛

【图 3:Cloudflare Smart Tiered Cache 已启用】

(70) Cloudflare 缓存 HIT 很快,MISS 却不稳定:回源阿里云杭州的一次真实优化

【图 3:简体中文站 Support 页面】

(71) 广告之外,社区项目如何长期活下去?我给 A Tour of Go 多语言项目加了 Support

图5:评论成功发布

(72) 从 Go Weekly 到 Reddit、DEV 和 Go Forum:第一次系统推广 A Tour of Go 多语言项目

【图 4:RTL 桌面课程布局修复后的效果】

(73) 第一次把 A Tour of Go 做成 RTL:阿拉伯语版本上线,以及我踩过的几个坑

多语言项目应该先做哪些语言?我的 66 个语言版本商业优先级排序

(74) 多语言项目应该先做哪些语言?我的 66 个语言版本商业优先级排序

当术语一致性遇到性能瓶颈:Go 多语言翻译项目的一次架构取舍

(75) 当术语一致性遇到性能瓶颈:Go 多语言翻译项目的一次架构取舍

从 A Tour of Go 走向 Go Learning & Documentation:为什么这个多语言项目需要 v2

(76) 从 A Tour of Go 走向 Go Learning & Documentation:为什么这个多语言项目需要 v2

Markdown 明明可以拆成很多段,为什么 v2 仍然坚持一个 Page 就是一个 TranslationUnit

(77) Markdown 明明可以拆成很多段,为什么 v2 仍然坚持一个 Page 就是一个 TranslationUnit

Tour、Learn、Docs 为什么不应该各维护一份术语表:v2 的统一 Glossary 设计

(78) Tour、Learn、Docs 为什么不应该各维护一份术语表:v2 的统一 Glossary 设计

v2 术语表变更后的页面影响范围判断流程:区分 Compatible 与 Affected,只处理真正受影响的页面。

(79) 术语表改了,为什么不应该让所有页面重新翻译?v2 的影响范围判断

CLI 性能优化示意图:通过 Prepare Once、Reuse Many Times,将执行时间从 6m54.554s 降至 10.335s,约提升 40.1 倍。

(80) 从 6 分 54 秒到 10.3 秒:Go 多语言项目一次 CLI 性能优化实战

Markdown Page 经过 Parse / Protect、Generation 和 Reconstruct / Validate 的流程示意图,强调保护 inline code、链接、代码等机器语义,同时允许译文按照自然语言调整语序。

(81) Markdown 不是纯文本:Learn / Docs 为什么需要新的 parser 与结构保护

历史为什么值得保留:复用已经完成的翻译成果,而不是重新做一遍

(82) 历史为什么值得保留:复用已经完成的翻译成果,而不是重新做一遍

历史状态通过 Trusted Checkpoint 建立可信断点,旧记录继续保留用于审计和诊断,后续工作流从当前状态继续向前,不再要求无限重建过去。

(83) 历史应该被保留,而不是被反复重建:v2 为什么最终需要一个“断点”

v2 依赖与失效传播流程图:从内容变化开始,评估依赖关系和真实影响,将结果区分为“仍然有效”和“需要失效”,只让真正受影响的状态重新进入流程。

(84) 一次内容变化,到底应该让哪些状态失效?v2 的依赖与失效传播设计

v2 本地内容覆盖判断流程图:官方英文页面先检查是否已有正式本地覆盖,有覆盖时使用本地 URL,没有覆盖时直接链接 go.dev,并保持本地路径真实 404。

(85) 有英文页面,不代表一定应该有本地页面:v2 如何处理本地内容覆盖、canonical 与真实 404

v2 代码注释完整性审计流程图:从源页面建立代码块清单,分类教学注释、机器语义和无法判断的内容,再与当前译文精确对应,确认 missing、extra 和 protected mutation 均为 0。

(86) 代码块里的注释为什么不能只靠肉眼检查?v2 如何统计并验证代码注释翻译完整性

结构化语义输入扩展示意图:同一份 books.yaml 原始文件保持不变,旧 parser 识别 10 个可本地化单元,当前 parser 识别 12 个,并新增 PDF 和 GitHub,确认旧单元无删除无修改后重新进入 Generation。

(87) 原始文件一个字没变,为什么还要重新翻译?从 books.yaml 10→12 看语义输入扩展

v2 Activation 流程图:Surface PASS 后先执行只读 activation-preflight 获取 prior_sha256,activation-apply 时通过 CAS 再次比较当前状态,只有 current 等于 prior 才提交 result_sha256,否则停止并重新 preflight。

(88) 审核都通过了,为什么上线前还要再检查一次?v2 的 Activation、prior SHA 与 CAS 设计

v2 分层验证流程图:TranslationUnit、Package Closure 和 Integrated Surface 均通过后进入 Activation,再由 Preview 检查 LoadContent、Compose、Resolver 和 Renderer 的真实运行链;如果实际使用错误 renderer,即使前置内容全部通过,Preview 仍然失败。

(89) Surface 已经 PASS,为什么 Preview 还是会失败?从一次 wrong renderer 看分层验证的价值

更快不一定更好:为什么我主动撤销了一次已经明显变快的性能优化

(90) 更快不一定更好:为什么我主动撤销了一次已经明显变快的性能优化

TranslationUnit 同类问题完整性示意图:左侧 Reviewer 只列出 3 个 examples,Generation 只修这 3 处后仍留下 5 个同类问题,re-QC 再次判 B;右侧 Reviewer 明确 defect category 和 bounded scope,Generation 执行 same-class complete sweep,最终同类残留为 0 并进入 re-QC A。

(91) 为什么修完 Reviewer 指出的所有例子,下一轮还是会失败?从 B→revision→B 看同类问题完整性

immutable source 与 replacement successor 示意图:左侧直接把旧 canonical source A 覆盖成 source B,会使旧 Generation、Review 和 Closure evidence 失去准确对应;右侧保留 source A 作为 immutable predecessor,为新正文建立 source B successor,并重新进入 corpus、glossary review、Generation、QC、closure、Surface 和 Activation 生命周期。

(92) 页面明明是我自己的,为什么不能直接重写?从 /translation/ 改版看 immutable source 与 replacement successor

protected representation 修订能力示意图:左侧 http.Client 被正确保护为 token;中间普通自然语言 Documentation 被错误保护为 opaque token,导致合法 revision 被阻塞;右侧保留旧 representation,通过 representation successor 建立新的可编辑表示,再继续 Generation 和独立 re-QC。

(93) 保护机制也会保护错东西:为什么一个 Documentation 能阻塞整页修订?

一个候选快照原本只应包含 1 个首页翻译单元,却因内容包范围未显式绑定而错误纳入 122 个翻译单元;通过 --content-package site-v2-shell 明确内容包后恢复到正确范围。

(94) 一个候选快照为什么突然多出 122 个单元?从隐式范围到显式内容包契约

Shell 自动化中,当前性检查命令失败并打印 RESULT=FAILED,但由于顶层子 Shell 中错误使用 return,后续命令仍继续执行,最终又打印出错误的 RESULT=PASS。

(95) 命令明明失败了,为什么最后还是 PASS?一次 Shell 自动化的 fail-closed 教训

【图8:Google AI 概览——引用网站的课程目录页】

(96) 同一个 Go 语言之旅网站,Bing、Google 和百度的搜索表现差距有多大?

多个正式命令原本分别重复构建当前内容成员、历史审核链、回执、SHA 和身份标识等可信环境;优化后改为先建立一次已验证的执行环境,再由 current-check、result-pack、import 等连续命令安全复用。

(97) 一个命令快了还不够:为什么我的性能优化开始转向跨命令环境复用

learn-docs-v1 原本以 49 个页面完成了翻译、审核和最终确认,后来发现还缺少 /doc/ 与 /doc/install 两个页面,导致内容包必须从 49 Page 迁移到 51 Page。图片对比了“后期补齐造成迁移成本”和“在 Generation 前先完成成员完整性审计”两种方式。

(98) 只是多了 2 个页面,为什么却触发了一次 49→51 的迁移?

【图2:维护者在 GitHub Issue #1 中回复,说明 math.pi 是官方课程有意设计的教学示例】

(99) 开源项目收到第一个 Issue:为什么我最终选择不修改代码?

一个翻译项目,为什么最后花了大部分时间证明基础设施?

(100) 一个翻译项目,为什么最后花了大部分时间证明基础设施?

【图2:GitHub Secret Scanning 显示 Google API Key 告警】

(101) GitHub 提示 Google API Key 泄露:为什么我最终选择了 Won’t fix?

上一篇记录了 A Tour of Go 多语言翻译项目首页手机端顶栏标题换行的问题。

那个问题本身最终只修改了几行 CSS,但真正发布到生产环境时,却意外暴露出了另一个更值得认真处理的问题:

新 release 切换以后,go-tour.service 因目录权限异常出现 status=203/EXEC,systemd 不断尝试重启,生产站点一度返回 502。

问题最终顺利恢复,但这次经历让我重新审视了 production 发布流程。

如果以后每次上线都还需要人工完成上传、调整权限、切换 current、重启服务、检查端口、判断是否回滚,那么发布本身就很容易成为新的故障来源。

于是,这次手机端 CSS 修复之后,我又继续完成了一件事情:

为 A Tour of Go 多语言翻译项目整理出第一版 production 自动部署脚本,并完成了第一次真实生产验证。

不过这次自动化过程本身也经历了一次很重要的“减法”:第一版脚本一度发展到 722 行,开始出现复杂状态机、部署锁所有权、多个退出码和 SSH 中断后的自动推断。

这让我想起了之前处理历史文章翻译项目时遇到的问题——自动化流程本身过于复杂,最后大量时间反而花在维护自动化工具,而不是完成核心工作。

所以这次最终目标变得非常明确:

自动部署脚本应该让发布更简单、更可靠,而不能变成另一个需要长期维护的大项目。

本文记录这整个过程。


一、一个很小的 CSS 发布,触发了 203/EXEC

前一篇完成手机端顶栏 CSS 修复以后,我生成了新的 production release,并准备切换生产版本。

新的 release 上传到了:

Plaintext
/data/go-tour/releases/20260813-zh-CN-a4d4dca

随后切换:

Plaintext
/data/go-tour/current

并重启:

Plaintext
go-tour.service

但服务没有正常起来。

systemd 开始不断自动重启,并反复出现:

Plaintext
status=203/EXEC
图 1:手工切换新 release 后,go-tour.service 因 release 目录权限异常反复出现 status=203/EXEC,systemd 连续尝试自动重启。修正 release 权限并恢复后,服务最终重新监听 127.0.0.1:3999。这次故障成为整理生产自动部署流程的直接契机。
图 1:手工切换新 release 后,go-tour.service 因 release 目录权限异常反复出现 status=203/EXEC,systemd 连续尝试自动重启。修正 release 权限并恢复后,服务最终重新监听 127.0.0.1:3999。这次故障成为整理生产自动部署流程的直接契机。

从日志中甚至可以看到 restart counter 连续增长:

Plaintext
47
48
49
50
51
52

这说明 systemd 自身其实一直在按照配置尝试恢复服务,但可执行文件根本没有正常启动条件。


二、真正的问题不是二进制,而是 release 根目录权限

继续检查以后,原因很快找到了。

新的 release 上传完成以后,目录权限继承成了类似:

Plaintext
drwx------ www:www

也就是:

Plaintext
0700
www:www

而 go-tour.service 并不是以 www 用户运行。

服务配置使用:

Plaintext
User=go-tour
Group=go-tour

因此即使:

Plaintext
bin/tour

本身具有执行权限,只要上层 release 目录不能被 go-tour 用户进入,systemd 仍然无法执行最终二进制。

这就是:

Plaintext
status=203/EXEC

的直接原因。

也就是说,问题并不是:

Go binary 编译坏了。

也不是:

systemd 配置坏了。

而是:

go-tour 用户根本无法穿过 release 根目录访问二进制。


三、先回滚,再修复权限

当时没有继续在故障版本上冒险修改,而是先把:

Plaintext
/data/go-tour/current

切回之前已经确认正常的 release。

旧版本重新启动以后:

Plaintext
go-tour.service

恢复 active,127.0.0.1:3999 重新返回 HTTP 200,生产站点也随之恢复。

然后再处理新的 release。

最终统一成:

  • owner/group:root:root
  • 所有目录:0755
  • 普通文件:0644
  • bin/tour:0755

也就是 release 不依赖上传端原来的 owner、group 和权限,而是在生产服务器上统一归一化。

调整完成以后再次切换,新版本成功启动。

这个问题虽然很快解决,却让我意识到:

只要 production 发布仍然依赖一连串人工操作,就总会存在某一步遗漏的可能。

今天是权限。

以后也可能是:

  • 上传不完整;
  • 校验和没有检查;
  • current 指错目录;
  • 服务刚显示 active 就误判成功;
  • localhost 实际还没准备好;
  • 公网 CDN 仍然返回旧资源;
  • 新版本失败以后忘记及时回滚。

于是开始考虑把已经验证过的人工流程固定下来。


四、最开始想把发布过程尽可能“保护完整”

第一版自动部署设计比较谨慎。

当时希望脚本能够处理尽可能多的边界情况,包括:

  • 本地 release 严格校验;
  • staging 上传;
  • deployment lock;
  • lock token;
  • 锁所有权判断;
  • 陈旧锁处理;
  • 多种本地退出码;
  • 多层 EXIT trap;
  • SSH 中断自动恢复;
  • 激活阶段状态机;
  • staging 自动清理;
  • current 切换临界窗口判断;
  • 自动回滚;
  • 回滚失败分类;
  • 公网异常分类。

结果脚本逐渐增长到:

Plaintext
722 行

从单个机制来看,每一个似乎都有理由。

但把它们组合起来以后,一个新的问题开始出现:

部署脚本本身变得越来越难判断。

例如一次 SSH 中断究竟属于:

  • 上传阶段失败;
  • staging 已完成;
  • final 已创建;
  • current 尚未切换;
  • current 可能已经切换;
  • restart 可能已经执行;
  • rollback 是否需要执行;
  • lock 是否应该删除;

为了覆盖这些情况,又需要继续增加状态变量和退出状态。

这时我开始觉得方向不对了。


五、历史文章翻译项目已经给过一次教训

之前在处理 WordPress 历史文章自动翻译项目时,我就遇到过类似问题。

为了让批量翻译流程足够可靠,逐渐增加:

  • 状态文件;
  • 恢复流程;
  • candidate;
  • execution evidence;
  • retry;
  • resume;
  • restart from current;
  • 各种错误分类和恢复入口。

这些能力本身都有用途。

但流程复杂到一定程度以后,经常出现一种情况:

本来应该排查文章为什么翻译失败,最后却变成排查“翻译自动化系统为什么认为这篇文章失败”。

也就是说,自动化工具开始抢走核心任务本身的时间。

生产部署脚本如果继续按 722 行这个方向发展,很可能以后也会变成:

本来只是想发布一个新版,却要先分析部署状态机为什么进入某个分支。

这显然违背了自动化的初衷。

所以这次决定主动做减法。


六、重新确定部署脚本的目标

新的目标不再是:

建设一套尽可能完备的 deployment framework。

而是:

把已经真实验证过的 production 发布步骤自动执行,并在真正危险的位置保留必要保护。

最终确定的优先级是:

可靠 > 简单 > 容易排错 > 极端场景全自动恢复

服务器本身也只有一个维护者,不存在复杂团队并发部署需求。

因此没有必要为了未来可能出现的多维护者场景增加大量逻辑。

deployment lock 仍然保留,但语义非常简单:

如果不存在:

Plaintext
/data/go-tour/.deploy.lock

就原子创建。

如果已经存在:

停止部署,提示可能存在未完成的上一次部署,人工检查。

不分析:

  • 这个锁是谁创建的;
  • token 是否匹配;
  • 是否已经陈旧;
  • 能不能自动接管。

七、722 行做了一次减法式重构

经过重新整理以后,脚本从:

Plaintext
722 行

降到了:

Plaintext
478 行

后来根据最终生产语义审计补了几个必要边界,最终定稿为:

Plaintext
494 行

删除的主要复杂机制包括:

  • 10/20/21/22/23/30 多层本地退出码协议;
  • deployment lock token/所有权文件;
  • 陈旧锁判断;
  • “另一个维护者的锁”判断;
  • 多层 EXIT trap;
  • 复杂远端自动清理状态机;
  • 多组交叉布尔状态;
  • 激活 SSH 异常后的自动猜测和恢复;
  • 重复的完整远端 manifest Python 校验;
  • 每个微秒级切换窗口的自动恢复尝试。

最终只保留真正和生产安全直接相关的部分。


八、最终保留了哪些保护

生产部署脚本最终保留的核心流程包括:

  1. 本地 production bundle 检查;
  2. release 名称安全检查;
  3. deployment lock;
  4. staging 上传;
  5. 不继承本地 owner/group/perms;
  6. 生产服务器统一权限归一化;
  7. 远端 SHA-256 校验;
  8. go-tour 用户访问权限检查;
  9. 同名 final release 禁止覆盖;
  10. 保存旧 current;
  11. staging 同文件系统重命名为 final;
  12. 临时 symlink + mv -Tf 原子替换 current;
  13. restart go-tour.service;
  14. 连续 3 次 systemd + localhost HTTP 健康检查;
  15. 新版本明确失败时自动回滚旧 release;
  16. localhost 健康以后才检查公网;
  17. 公网/CDN 异常不回滚已经健康的源站。

最终正式提交:

Plaintext
3852bc1
feat: 添加生产发布自动部署脚本
图 2:经过减法式重构和最终生产语义审计后,生产自动部署脚本正式进入仓库。最终脚本约 494 行,只保留 staging、权限归一化、SHA-256、原子切换、连续健康检查和失败回滚等核心安全机制。
图 2:经过减法式重构和最终生产语义审计后,生产自动部署脚本正式进入仓库。最终脚本约 494 行,只保留 staging、权限归一化、SHA-256、原子切换、连续健康检查和失败回滚等核心安全机制。

九、一个很重要的设计:生产已经坏了,也应该允许部署

最终安全审计时还发现了一个很关键的问题。

脚本曾经要求旧 release 对:

Plaintext
go-tour

用户仍然可执行。

看起来很合理:

回滚目标最好应该是可用的。

但仔细想以后就会发现,这个要求存在严重问题。

如果 production 当前恰好就是因为:

Plaintext
203/EXEC

而故障,那么:

旧 release 不可执行。

按照这个前置条件,脚本反而会拒绝部署新的修复版本。

这就出现了悖论:

生产坏了,所以需要部署修复版本;
但因为生产坏了,所以部署脚本不允许部署。

最终把这个硬门槛删除。

现在旧 current 在部署开始时只要求:

  • 是 symlink;
  • readlink -f 能解析;
  • 对应目录真实存在;
  • 位于 /data/go-tour/releases/ 下面。

不要求:

  • 旧 binary 可执行;
  • 旧 release 当前健康;
  • systemd active;
  • localhost HTTP 200。

这样即使 production 当前已经坏了,仍然可以使用自动部署脚本发布修复版本。


十、旧版本不健康,也不能谎报“回滚成功”

放宽部署前条件以后,还必须解决另一个语义问题。

考虑这种情况:

当前 production 本来就是坏的 → 部署一个修复版本 → 修复版本也失败 → 脚本把 current 切回 old。

这时只能说明:

symlink 已经切回旧 release。

不能说明:

生产已经恢复。

因此自动回滚以后,脚本仍然会:

  1. restart go-tour.service;
  2. 检查 systemd;
  3. 检查 localhost HTTP;
  4. 连续 3 次成功以后才认为旧版本恢复健康。

只有真正通过,才输出类似:

Plaintext
rollback completed; old release is healthy

否则:

  • 保留 deployment lock;
  • 保留现场;
  • 停止继续自动处理;
  • 提示人工检查。

这个边界最终也通过了审计。


十一、第一次真实使用自动部署脚本

脚本提交并推送以后,我没有直接把它当作“已经完成”。

还需要一次真正的 production 验证。

于是基于当时仓库生成新的 release:

Plaintext
/tmp/go-tour-release-20260813-zh-CN-3852bc1

publish 状态为:

Plaintext
locale=zh-CN
ready=103
pending=0
blocked=0
pages=103
articles=7

然后第一次真正执行:

Plaintext
scripts/deploy-production.sh \
    /tmp/go-tour-release-20260813-zh-CN-3852bc1

整个流程自动完成:

  • 本地 release preflight;
  • 远端 deployment lock;
  • staging;
  • rsync;
  • 权限归一化;
  • SHA-256;
  • go-tour 用户权限检查;
  • final release;
  • current 原子切换;
  • restart;
  • localhost 健康检查;
  • 公网验收。

而这次第一次真实执行,还验证了一个之前非常值得保留的设计。


十二、systemd 已经 active,应用却还没有真正准备好

restart 之后第一次健康检查出现:

Plaintext
service=active HTTP=000

也就是说:

systemd 已经认为进程是 active。

但是:

localhost 还没有得到正常 HTTP 响应。

随后才出现:

Plaintext
active + HTTP 200 (consecutive 1/3)
active + HTTP 200 (consecutive 2/3)
active + HTTP 200 (consecutive 3/3)

最终脚本才判定部署成功。

图 3:生产自动部署脚本第一次真实运行时,systemd 已经显示 active,但首次 localhost 探测仍然得到 HTTP 000;随后连续 3 次同时满足 active + HTTP 200 后,脚本才判定部署成功,并继续完成公网 HTTP 200 验收。这次真实运行验证了连续应用层健康检查的必要性。
图 3:生产自动部署脚本第一次真实运行时,systemd 已经显示 active,但首次 localhost 探测仍然得到 HTTP 000;随后连续 3 次同时满足 active + HTTP 200 后,脚本才判定部署成功,并继续完成公网 HTTP 200 验收。这次真实运行验证了连续应用层健康检查的必要性。

这一幕非常有价值。

因为此前人工部署时,很容易使用:

Bash
systemctl is-active go-tour.service

看到:

Plaintext
active

以后就认为:

服务已经好了。

但第一次真实自动部署已经证明:

进程已经运行,并不等于应用已经可以正常服务请求。

这也是为什么最终没有把健康检查简化成一次 systemctl is-active。


十三、为什么要求连续 3 次 HTTP 200

最终健康标准是:

每一次都必须同时满足:

Plaintext
systemctl is-active == active

以及:

Plaintext
http://127.0.0.1:3999/ == HTTP 200

而且必须:

Plaintext
连续 3 次

只要其中一次失败:

连续计数重新归零。

最多检查:

Plaintext
12 轮

间隔:

Plaintext
3 秒

第一次真实运行中的:

Plaintext
active + HTTP 000

恰好证明了这个机制不是多余防御。


十四、公网/CDN 验收必须和源站分开

localhost 连续健康以后,脚本还会检查:

Plaintext
https://go-dev.shuijingwanwq.com/

第一次真实部署中最终得到:

Plaintext
public acceptance passed: HTTP 200

不过这里还有一个非常重要的设计原则:

公网失败不会自动回滚已经健康的源站。

原因是前一篇手机端 CSS 修复已经遇到了 EdgeOne 缓存问题。

可能出现:

Plaintext
localhost 正常
Nginx 正常
production release 正常
EdgeOne 仍缓存旧 CSS

如果脚本看到公网内容异常以后就自动回滚,那么:

一个健康的新版本会因为 CDN 缓存问题被错误撤回。

因此最终把两层明确分开:

源站健康

决定:

新 release 是否能够继续运行。

公网/CDN 验收

决定:

是否还需要继续排查 EdgeOne、HTTPS、Nginx 或缓存。

公网检查可以返回非零,但不会自动回滚一个已经连续健康的源站 release。


十五、第一次真实自动部署最终闭环

脚本执行完成以后,又单独做了一次最终现场检查。

结果为:

Plaintext
CURRENT:
/data/go-tour/releases/20260813-zh-CN-3852bc1

DEPLOY LOCK:
NO LOCK

SERVICE:
active

LOCAL HTTP:
200
图 4:首次自动部署完成后的最终生产状态。current 已指向新 release,deployment lock 已正确释放,go-tour.service 保持 active,localhost 返回 HTTP 200,整个部署事务完整收口。
图 4:首次自动部署完成后的最终生产状态。current 已指向新 release,deployment lock 已正确释放,go-tour.service 保持 active,localhost 返回 HTTP 200,整个部署事务完整收口。

这说明第一次真实运行已经完整验证:

  • release 正确上传;
  • 权限正确;
  • SHA-256 正确;
  • current 正确切换;
  • 服务正确启动;
  • localhost 正常;
  • 公网正常;
  • deployment lock 正确释放;
  • 没有 staging 残留;
  • 没有触发人工恢复;
  • 没有发生错误回滚。

十六、现在的正常 production 发布流程

完成这次自动化以后,以后正常生产发布流程已经明显简单很多。

首先生成 release:

Bash
GOOS=linux GOARCH=amd64 go run -mod=readonly ./cmd/tour-i18n publish \
    --locale zh-CN \
    --published-at "$published_at" \
    --output /tmp/go-tour-release-...

然后执行:

Bash
scripts/deploy-production.sh \
    /tmp/go-tour-release-...

剩余过程由脚本负责:

  • 上传;
  • 权限归一化;
  • SHA-256;
  • staging;
  • final;
  • current;
  • restart;
  • 连续健康检查;
  • 必要回滚;
  • 公网验收。

从日常维护角度看,这才是这份脚本真正的价值。

不是因为它有多少功能。

而是:

发布时需要人工记住的步骤明显减少了。


十七、哪些事情故意没有自动化

这次最终还专门保留了一些“不自动处理”的边界。

1. deployment lock 已经存在

直接停止。

不自动判断:

是不是陈旧锁。

也不自动删除。

因为只有一个维护者,如果看到:

Plaintext
/data/go-tour/.deploy.lock

存在,更合理的行为就是:

先确认上一次部署发生了什么。


2. SSH 恰好在 current 切换期间断开

不尝试自动猜:

到底切了还是没切。

脚本会保留:

  • lock;
  • release;
  • 现场。

然后提示人工检查:

Bash
ssh aliyun 'readlink -f /data/go-tour/current'
ssh aliyun 'systemctl status go-tour.service --no-pager -l'
ssh aliyun 'curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3999/'
ssh aliyun 'journalctl -u go-tour.service -n 80 --no-pager'

这种极少发生的临界情况,人工判断比继续构建几十种自动恢复分支更可靠。


3. EdgeOne 缓存

脚本不调用 EdgeOne API。

如果:

源站已经正确,但公网仍显示旧 CSS。

就单独人工检查 CDN。

这和 production release 是否健康属于不同问题。


十八、这次最大的收获不是脚本本身

这次最终确实得到了一份:

Plaintext
494 行

的 production 自动部署脚本。

但我觉得真正重要的并不是“终于写了一个部署脚本”。

而是重新确认了一个对长期项目非常重要的原则:

自动化应该消灭重复劳动,而不是制造新的维护对象。

最初的 722 行版本,从“覆盖更多异常”的角度看其实更完整。

但长期维护真正需要考虑的是:

当半年后部署失败时,我能不能快速看懂它在做什么?

如果答案是:

需要重新研究一套复杂退出状态协议和状态机。

那么它就已经开始偏离最初目的。

最终这版选择:

  • 正常路径自动完成;
  • 明确失败自动回滚;
  • 不确定状态停止;
  • 极端边界人工确认。

对当前:

单维护者 + 单服务器 + 单 production 服务

的场景已经足够。


十九、从手工故障到自动部署,形成了一个完整闭环

回头看,这次事情最初只是:

手机首页标题最后一个“目”换行了。

但后续链路变成:

修 CSS → 发布 production → release 权限异常 → 203/EXEC → 回滚 → 修复权限 → 重新上线 → EdgeOne 缓存 → 真机验证 → 重新审视手工部署 → 自动部署脚本 → 脚本过度复杂 → 减法式重构 → 最终语义审计 → 第一次真实自动部署。

这也是长期维护项目中很常见的一种演进方式。

真正推动基础设施完善的,往往不是:

我今天决定设计一套发布系统。

而是:

某个真实故障终于证明了这里值得自动化。


总结

这次 A Tour of Go 多语言翻译项目 production 自动部署工作的最终结果是:

Plaintext
production release:
20260813-zh-CN-3852bc1

ready=103
pending=0
blocked=0
pages=103
articles=7

current:
正确切换

deployment lock:
已释放

go-tour.service:
active

localhost:
HTTP 200

public:
HTTP 200

而自动部署脚本最终保留的原则也很简单:

上传先 staging,权限统一归一化,文件必须校验,current 原子切换,不能只相信 systemd active,新版本明确失败才自动回滚,状态不确定时不要猜。

经历了最初 722 行的复杂版本以后,我现在反而更认可这种方式:

一份生产脚本最重要的并不是能够自动处理所有理论异常,而是正常情况下足够省事,异常情况下足够容易理解。

以后没有真实部署故障证据,这份第一版脚本不会继续为了假设中的边界增加功能。

真正遇到新的生产问题时,再根据真实问题决定是否值得修改。

Go 学习与文档多语言本地化项目

本系列完整记录 Go 学习与文档多语言本地化项目从 A Tour of Go 起步,逐步扩展到站点首页、项目说明页、学习内容、文档以及未来内容包的实际开发过程,包括架构设计、统一术语治理、整页翻译、结构保护、自动校验、独立质量审核、生产发布与长期维护。

项目源码:
✅ GitHub:shuijingwan/go-tour-i18n

语言版本:

当前跨项目目标语言池共包含 66 个语言版本。Go 项目本身目前提供 65 个社区 Production 语言版本,下面每一门 Go 语言版本都直接链接到其当前公开站点。语言列表沿用项目首页现有的展示顺序。

英语(美国)仅作为跨项目目标语言纳入列表,并不是单独的 Go Production 语言版本。当前 Go 的英文源内容仍为官方 generic English,因此英语(美国)链接到 Go 官方站点,而不是不存在的本地社区部署。

  1. 阿姆哈拉语
  2. 阿拉伯语
  3. 孟加拉语
  4. 葡萄牙语(巴西)
  5. 保加利亚语
  6. 加泰罗尼亚语
  7. 克罗地亚语
  8. 捷克语
  9. 丹麦语
  10. 荷兰语
  11. 英语(美国)(Go 官方英文站点)
  12. 英语(澳大利亚)
  13. 英语(加拿大)
  14. 英语(印度)
  15. 英语(新加坡)
  16. 英语(南非)
  17. 英语(英国)
  18. 爱沙尼亚语
  19. 菲律宾语
  20. 芬兰语
  21. 法语(法国)
  22. 法语(加拿大)
  23. 德语(德国)
  24. 德语(奥地利)
  25. 德语(瑞士)
  26. 希腊语
  27. 古吉拉特语
  28. 希伯来语
  29. 印地语
  30. 匈牙利语
  31. 印度尼西亚语
  32. 意大利语
  33. 日语
  34. 卡纳达语
  35. 哈萨克语
  36. 韩语
  37. 西班牙语(拉丁美洲)
  38. 拉脱维亚语
  39. 立陶宛语
  40. 马来语
  41. 马拉雅拉姆语
  42. 马拉地语
  43. 书面挪威语(Bokmål)
  44. 波斯语
  45. 波兰语
  46. 葡萄牙语(葡萄牙)
  47. 旁遮普语(果鲁穆奇文,印度)
  48. 罗马尼亚语
  49. 俄语
  50. 塞尔维亚语(西里尔文)
  51. 简体中文(中国大陆)
  52. 简体中文(新加坡)
  53. 斯洛伐克语
  54. 斯洛文尼亚语
  55. 西班牙语(西班牙)
  56. 斯瓦希里语(坦桑尼亚)
  57. 瑞典语
  58. 泰米尔语
  59. 泰卢固语
  60. 泰语
  61. 繁体中文(台湾)
  62. 繁体中文(香港)
  63. 土耳其语
  64. 乌克兰语
  65. 乌尔都语
  66. 越南语

项目正在持续扩展新的 Go 学习与文档内容,并长期维护各语言版本的术语一致性、翻译质量、独立审核、生产发布与后续更新。

本项目属于非官方社区多语言本地化项目,与 Go 官方无隶属、授权或背书关系。