v3.1 + 批次0: 智能回复重构基线 - ApprovalMatcher + 关键词降级 + 文档速修 + v4.0任务书面化

docs/09-部署运维/DEPLOY-GUIDE.md

@@ -164,6 +164,40 @@ ping itsupport.servyou.com.cn
 # CORS_ORIGINS=http://10.90.5.110
 ```
 
+### 4.3 部署铁律（2026-07-17 新增，踩坑记录）
+
+以下 3 条均为生产事故复盘得出的硬性规则，部署/变更时必须遵守：
+
+#### 铁律 1：backend 必须 `--workers 1`（WS 推送单 worker 约束）
+
+`ws_manager` 是进程内单例，AI 后台任务与员工 WebSocket 连接若落在不同 worker 进程，`broadcast_to_employees` 会**静默丢失约 50% 消息**。
+
+```bash
+# ❌ 危险：docker-compose-override.yml 会自动合并覆盖主文件！
+# 若 override 中存在 --workers 2，主文件的 --workers 1 会被覆盖
+docker compose -f docker-compose.yml -f docker-compose-override.yml config | grep workers
+# 必须输出 1。如为 2，删除或修改 override 文件
+```
+
+#### 铁律 2：`.env` 变量不会自动传入容器，必须在 `environment:` 显式声明
+
+`backend/.dockerignore` 排除了全部 `.env` 文件，生产容器配置 **100% 来自 docker-compose.yml 的 `environment:` 部分**。新增任何环境变量（尤其是 `DIFY_NATIVE_BASE_URL`、`DIFY_NATIVE_API_KEY`），必须：
+
+```yaml
+# docker-compose.yml
+backend:
+  environment:
+    - DIFY_NATIVE_BASE_URL=${DIFY_NATIVE_BASE_URL:-}
+    - DIFY_NATIVE_API_KEY=${DIFY_NATIVE_API_KEY:-}
+```
+
+验证：容器内执行 `env | grep DIFY_NATIVE` 非空；后端日志出现「调用 Dify 原生 API」而非「回退到代理路径」。
+（事故记录：2026-07-13 两次因未声明导致 P0 故障；`WECOM_SSO_CALLBACK_BASE` 未声明导致扫码登录崩溃）
+
+#### 铁律 3：Redis 密码含特殊字符必须 URL 编码
+
+`REDIS_URL` 中密码含 `@ # !` 时未编码 → 解析出错误的 host → 连接挂起 → 登录 502。编码规则：`@→%40`、`#→%23`、`!→%21`。改密码时须同步更新 compose 中 `requirepass` 与 `REDIS_URL` 两处。
+
 ---
 
 ## 五、启动服务