diff --git a/docs/deploy-production.md b/docs/deploy-production.md
new file mode 100644
index 0000000..ca00e6b
--- /dev/null
+++ b/docs/deploy-production.md
@@ -0,0 +1,200 @@
+# 线上部署文档（生产环境实录）
+
+> 更新：2026-09-30 · 对应线上版本 `5d83dd9`
+> 本文记录**实际部署状态**（不是理想方案），排查问题和重新部署都以此为准。
+
+## 1. 线上环境总览
+
+| 项 | 值 |
+|---|---|
+| 目标服务器 | 阿里云 ECS（境外）`47.254.176.10`，Debian 13，Docker 29.4.0，1Panel 面板 |
+| 跳板机 | 国内阿里云 `8.152.213.143`（境外机直连不通，必须经跳板） |
+| 线上域名 | `https://chat2.agent.hnxinyouhe.com`（1Panel 建站，HTTPS 证书已绑定） |
+| 应用容器 | `hs-ai-kefu`（端口 `8017:8000`，内存限额 512M） |
+| 代码位置 | `/opt/1panel/www/sites/chat2.agent.hnxinyouhe.com/index`（git clone 自公司 git） |
+| git 仓库 | `http://219.157.255.213:25311/xinyouhe/ai-kefu-jc.git` |
+
+**同服务器共存的其它项目（部署/排障时绝对不要碰）**：
+汽车客服 `cc-ai-kefu`（`chat.agent.hnxinyouhe.com`，端口 8016）、tracker 系列、
+photo-live 系列、php7433 等。本项目与它们仅共享 Docker 守护进程，容器/端口/目录/数据完全隔离。
+
+## 2. SSH 连接方式（专属密钥 + 跳板链路）
+
+本机 `~/.ssh/config` 已配好两个别名（密钥为本项目专属 `~/.ssh/ai_kefu_jc_deploy`，
+吊销 = 删服务器 `~/.ssh/authorized_keys` 中带 `ai-kefu-jc-deploy` 注释的行）：
+
+```
+Host ai-kefu-jc-bastion          # 跳板（国内）
+    HostName 8.152.213.143 / User root / Port 22
+
+Host ai-kefu-jc-prod             # 目标（境外，经跳板）
+    HostName 47.254.176.10 / User root / Port 22
+    ProxyJump ai-kefu-jc-bastion
+```
+
+```bash
+ssh ai-kefu-jc-prod 'echo ok'    # 一键直达到目标服务器
+```
+
+## 3. 服务器上的实际布局
+
+```
+/opt/1panel/www/sites/chat2.agent.hnxinyouhe.com/
+├── index/                    ← 项目根（git 仓库，即部署目录）
+│   ├── app/ static/ tests/ ...
+│   ├── docker-compose.yml    ← 注意：服务器上有本地改动(mem_limit 512m，未提交)
+│   ├── deploy.sh             ← 同上（本地改动）
+│   ├── data/hesupipe_ai_kefu.db   ← 生产 SQLite（容器卷挂载，gitignore）
+│   └── .env                  ← 生产配置（gitignore，权限600）
+├── log/                      ← 站点访问日志
+├── ssl/                      ← HTTPS 证书（1Panel 管理）
+└── proxy/                    ← 反代配置（1Panel 站点的 include 加载）
+    ├── root.conf             ← HTTP 全站反代 → 127.0.0.1:8017
+    └── ws.conf               ← WebSocket 专用路由（与汽车客服同款）
+```
+
+1Panel 主配置：`/opt/1panel/www/conf.d/chat2.agent.hnxinyouhe.com.conf`
+（其中第 19 行 `include /www/sites/chat2.agent.hnxinyouhe.com/proxy/*.conf;`
+是部署时手工补的 —— **1Panel 建站默认不带 include，面板配的反代不会生效**，
+备份在同目录 `*.conf.bak.20260930`）。
+
+### 反代实际生效配置（排查时对照）
+
+`proxy/root.conf`（HTTP）：
+```nginx
+location ^~ / {
+    proxy_pass http://127.0.0.1:8017;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 300s;
+}
+```
+
+`proxy/ws.conf`（WebSocket 专用，`/ws/` 前缀优先命中）：
+```nginx
+location /ws/ {
+    proxy_pass http://127.0.0.1:8017;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+```
+
+> ⚠️ 反代改动后要重载：`docker exec $(docker ps --filter name=openresty -q | head -1) nginx -t && nginx -s reload`
+> （先 `-t` 语法检查再 reload；reload 是平滑的，不影响其他站点）
+
+## 4. 生产 .env（结构，值脱敏）
+
+```ini
+AI_PROVIDER=glm
+ZHIPU_API_KEY=<与汽车项目同一个>
+AI_MODEL=glm-4-flash
+ZHIPU_BASE_URL=<同汽车项目>
+
+DATABASE_URL=sqlite+aiosqlite:///./data/hesupipe_ai_kefu.db
+
+SMTP_HOST/PORT/USER/PASS=<真实发件账号，同汽车项目>
+NOTIFY_EMAIL=hesu@hesuu.com            # 询盘通知收件箱
+
+PUSH_ENABLED=false                      # 暂不推送 UniService（需求方决定）
+PUSH_API_URL=https://uniservice.server.hnxinyouhe.com/open/v1/inquiry/push
+PUSH_API_KEY=<已备好，开启时用>
+PUSH_EXTERNAL_KEY_PREFIX=ai-kefu-jc     # 与汽车项目线索键隔离，勿改！
+
+APP_HOST=0.0.0.0
+APP_PORT=8017
+APP_DEBUG=false
+```
+
+凭据来源：部署时从汽车项目服务器上的 `.env`（`chat.agent.hnxinyouhe.com/index/.env`）
+提取同类键，**只读未动**。
+
+## 5. 部署 / 更新流程（日常发版照此执行）
+
+```bash
+# 0. 本地：测试全绿才发版
+python -m pytest -q          # 231 项
+
+# 1. 本地：推送
+git push origin master
+
+# 2. 服务器：更新并重建（一条命令）
+ssh ai-kefu-jc-prod '
+cd /opt/1panel/www/sites/chat2.agent.hnxinyouhe.com/index
+git stash && git pull && git stash pop    # stash 保住服务器本地改动(mem_limit等)
+docker compose build && docker compose up -d
+sleep 3 && curl -s http://127.0.0.1:8017/health
+'
+```
+
+说明：
+- 静态文件（widget.js 等）**打进镜像**，改前端必须 `build`（仅 `up -d` 不够）
+- `.env` 和 `data/` 不在 git 里，更新不受影响
+- 回滚：`git checkout <上一版本> && docker compose build && docker compose up -d`
+
+## 6. 验证清单（发版后必跑）
+
+```bash
+# ① 健康
+curl -s https://chat2.agent.hnxinyouhe.com/health            # {"status":"ok"}
+# ② 页面
+curl -s https://chat2.agent.hnxinyouhe.com/ | grep -o "<title>.*</title>"
+# ③ WebSocket（期待 HTTP/1.1 101）
+curl -s -i --http1.1 -H "Connection: Upgrade" -H "Upgrade: websocket" \
+  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" -H "Sec-WebSocket-Version: 13" \
+  https://chat2.agent.hnxinyouhe.com/ws/chat | head -1
+# ④ 静态与缓存头
+curl -sI https://chat2.agent.hnxinyouhe.com/static/widget.js | grep -i "cache\|HTTP"
+```
+
+功能级验证（改前端/挂件后）：打开
+`https://chat2.agent.hnxinyouhe.com/static/widget-test.html`，
+用 Playwright 或肉眼核对：邀请卡 5 秒弹出位置、面板四个方位（data-position）、
+头像加载、主题色断言面板 9/9 绿。
+
+## 7. 本次上线踩坑实录（排查手册）
+
+| 现象 | 根因 | 解法（已内置，重蹈覆辙时对照） |
+|---|---|---|
+| WS 握手 426（HTTP 正常） | 1Panel 面板生成的反代里 `Upgrade/Connection` 头**重复定义两套**，uvicorn 严格解析直接拒绝 | 拆分 ws.conf 单套路（§3），`nginx -T` dump 最终配置 + 假后端 dump 收到的头可快速定位 |
+| 改了 widget.js 线上"没生效" | 响应无 Cache-Control，浏览器启发式缓存旧脚本 | 已加中间件 `/static/* → Cache-Control: no-cache`（ec2d17b）；用户端 Ctrl+F5 一次即愈 |
+| bottom-left 弹出元素溢出屏幕（面板 x=-183） | 弹出层（chat-panel / invite-container）CSS 硬编码 `right:0` 只适配右下角 | 已随 `pos-<position>` 类联动（5d83dd9），静态测试锁死；**新增弹出元素时必须同时加联动规则** |
+| 1Panel 配了反代不生效 | 面板建站的主 conf 默认不含 `include proxy/*.conf` | 手工补 include 行（§3），备份后 reload |
+| deploy 时 `git pull` 报本地改动冲突 | 服务器 compose/deploy.sh 有本地改动（mem_limit） | `git stash && git pull && git stash pop`（已写入 §5 流程） |
+
+## 8. 常见运维操作
+
+```bash
+# 看应用日志（最近100行）
+ssh ai-kefu-jc-prod 'docker logs hs-ai-kefu --tail 100'
+
+# 重启应用（不动其他容器）
+ssh ai-kefu-jc-prod 'cd /opt/1panel/www/sites/chat2.agent.hnxinyouhe.com/index && docker compose up -d --force-recreate'
+
+# 容器状态/内存
+ssh ai-kefu-jc-prod 'docker stats hs-ai-kefu --no-stream'
+
+# 破防率观测（上线第一周必做，见 CLAUDE.md 观察期）
+ssh ai-kefu-jc-prod 'docker exec hs-ai-kefu python scripts/breach_rate.py'
+
+# 管理后台
+https://chat2.agent.hnxinyouhe.com/admin   # 密码在生产 .env 同汽车项目口径
+```
+
+## 9. 待办与提醒
+
+- [ ] 官网嵌入：hesupipe.com 按 `docs/embed-guide.md`（script src 用
+      `https://chat2.agent.hnxinyouhe.com/static/widget.js`，位置/配色/邮箱可配）
+- [ ] 邮件通道冒烟：跑一轮测试留资，确认 hesu@hesuu.com 能收到询盘邮件
+      （单邮件通道，SMTP 失败不自动补发，上线头几天盯收件）
+- [ ] 开启 UniService 推送（届时只改 `.env` 的 `PUSH_ENABLED=true` 并重启容器）
+- [ ] 上线第一周：跑 breach_rate 观测漏放/误杀（已知 4 项残差见 docs/test-checklist.md）
+- [ ] 服务器本地改动（compose mem_limit / deploy.sh）择机整理进 git，消除 stash 依赖