Phorge 现代化改造实战（十三）：联调六项外部服务，容器在运行，不代表业务已经切换
内容提要
本文介绍Phorge现代化改造中六个Gorge服务与Phorge整体联调的方法。文章强调容器状态、健康探针和配置就绪均不能证明业务已生效，需分五阶段验证：运行、可达、就绪、被选中和业务生效。针对高亮、文件存储、邮件、搜索、通知和Webhook各自不同的接入机制，需分别检查引擎选择、优先级、后端配置和队列消费等细节，最终以真实业务结果为准。
延伸解读
容器状态不等于业务生效
文章强调，即使所有容器显示 Up、健康检查通过，也不代表业务已切换。因为服务可能只是进程活着，但配置未生效或未被选中。例如，高亮服务即使配置了地址，仍需切换引擎并清缓存；文件存储即使配置了地址，原生引擎仍优先。因此，必须通过真实业务操作验证最终效果。
配置写入与回滚的边界
配置写入是幂等的，但留空不会删除已有配置，回滚时需显式恢复。例如，文件存储切换后，若删除容器或清空配置，已写入Gorge的文件将失去读取路径。Webhook回滚需先取消交接配置，再停服务，否则队列中的请求会长期滞留。理解这些边界有助于避免数据丢失或服务中断。
依赖顺序与健康检查的权衡
编排中，对file-storage和webhook使用service_started而非service_healthy，是为了避免循环依赖：这两个服务依赖Phorge创建的数据库，而Phorge又依赖它们就绪。首次启动时短暂unhealthy是预期的，这种设计比简单等待更合理。健康检查应区分healthz和readyz，避免因后端未配置而阻塞整个站点启动。
测试后端的局限
mailer和search的测试后端（如test类型）只能验证协议连通，不能验证真实后端（如SMTP、Elasticsearch）的功能，且内存索引重启后消失。Webhook没有测试后端，必须连接真实数据库。因此，测试后端适合开发调试，生产验收必须使用真实后端并执行端到端测试。
Q&A
Phorge 现代化改造中，如何判断六个 Gorge 服务是否真正接管了业务？
不能仅凭容器状态、健康探针或配置就绪来判断，需要分五个阶段验证：运行、可达、就绪、被选中和业务生效。最终以真实业务结果为准，例如高亮要实际看到新渲染，文件上传后检查存储引擎，邮件能收到测试邮件等。
Phorge 中如何切换高亮引擎到 Gorge？
需要设置 syntax-highlighter.engine 为 PhabricatorGorgeSyntaxHighlighterEngine，并执行 bin/cache purge --all 清除缓存。然后重新打开一个包含内置引擎不支持语言的 Paste 或 diff，确认页面出现新高亮。
Phorge 文件存储切换到 Gorge 时，为什么配置了 gorge.file.uri 后文件仍可能写入 MySQL？
因为 Phorge 选择写入引擎时按 priority 排序，原生 MySQL blob 引擎优先级高于 Gorge。需要将 storage.mysql-engine.max-size 设为 0 来禁用原生可写后端，并删除 storage.local-disk.path 和 storage.s3.bucket 的本地覆盖值，然后检查引擎顺序，确保 Gorge 成为第一个可写引擎。
Phorge 邮件服务联调时，如何验证邮件链路是否正常？
配置 MAILER_TYPE=smtp 及 SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD 等，重启 gorge-mailer 后检查 /readyz 状态，然后使用 bin/mail send-test 发送测试邮件，并确认收到。
Phorge 搜索服务联调时，为什么只建索引不执行全量回填会导致查询结果为空？
因为只建索引（search init）会删除并重建索引，但不会填充数据。需要执行 search index --all --force 进行全量回填，否则索引中没有文档，查询自然返回空结果，容易被误判为业务数据不存在。
Phorge 通知服务联调时，为什么浏览器无法连接 gorge-notification 的 admin 端口？
因为 admin 端口（22281）仅供 Phorge 后端访问，浏览器需要连接 client 端口（22280）。client 端口地址会被拼成 WebSocket URI 交给浏览器，浏览器不在 Compose 网络内，因此必须使用 127.0.0.1:22280 或用户浏览器可访问的域名，且 HTTPS 页面需要 wss://。
Phorge Webhook 切换到 Gorge 后，回滚时需要注意什么顺序？
回滚时先清除 gorge.webhook.uri 配置，让 Phorge 恢复为新请求安排 HeraldWebhookWorker，然后再停止 gorge-webhook 服务。如果先停服务，停止到清配置之间创建的请求会没有 PHP 任务，Go 也不再轮询，导致请求长期留在 queued 状态。
Phorge 联调时，为什么不能对所有 Gorge 服务都使用 depends_on: service_healthy？
因为 gorge-file-storage 和 gorge-webhook 依赖 Phorge 创建的数据库（phabricator_file 和 phabricator_herald），而 Phorge 又依赖这些服务就绪，形成循环依赖。因此对 file-storage 和 webhook 只能使用 service_started，先让进程存在，再允许 Phorge 建库，库出现后服务的 /readyz 会自行恢复。
Phorge 联调时，Config 页面中 Unreachable、Not Ready、Not In Use 分别代表什么？
Unreachable 表示拓扑问题，服务不可达；Not Ready 表示服务依赖问题，服务活着但后端未就绪；Not In Use 表示业务选择问题，服务未在 Phorge 配置中被启用。三者含义不同，排障时应区分对待。
