diff --git a/CLAUDE.md b/CLAUDE.md
index e019575..e57436e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,6 +72,27 @@ bash deploy.sh    # docker compose 构建并启动，健康检查 127.0.0.1:8017
 - 聊天演示页 `/`，管理后台 `/admin`，健康检查 `/health`。
 - 挂件嵌入官网指引：`docs/embed-guide.md`。
 
+## 部署注意事项（血泪教训，勿重蹈覆辙）
+
+线上完整手册见 `docs/deploy-production.md`（环境/反代配置/发版流程/踩坑实录）。
+以下是最容易再犯的坑：
+
+1. **⚠️ compose 项目名（互删事故根因，勿删 `name:` 行）**：1Panel 站点目录都叫
+   `index`，docker compose 默认以目录名为项目名——曾与汽车项目
+   （`chat.agent.hnxinyouhe.com/index`）撞名成同一 project "index"，导致
+   **任一目录 down/up 互删对方容器**（起一个、另一个 502）。已在 compose 固定
+   `name: hs-ai-kefu` 根治。**任何部署到 1Panel 的新项目都必须显式设置
+   compose 项目名**；汽车项目（仍叫 index）若再出新互斥，同样加 `name:` 解决。
+2. **挂件静态文件打进镜像**：改 `static/` 必须 `docker compose build`，仅 `up -d` 不生效。
+3. **1Panel 反代**：面板配完反代需确认主 conf（`conf.d/<域名>.conf`）里有
+   `include .../proxy/*.conf;` 行；WebSocket 走 `proxy/ws.conf`（单套升级头，
+   重复两套会被 uvicorn 拒成 426）；改后 `nginx -t` 再 reload。
+4. **同页面嵌多个挂件**（如官网同时挂汽车+建材客服）：两挂件源自同一代码，
+   `sessionStorage` 邀请卡 key（`widget_invite_dismissed_<path>`）与 host id
+   （`cc-widget-host`）**同名互相干扰**——需要同页共存时先给全局命名加项目前缀。
+5. **服务器上不许有未提交改动**：`git status` 应干净；改动请进 git 再部署，
+   避免回到 stash 时代（pull 冲突）。
+
 ## 上线观察期（第一周必做）
 
 上线不是终点。**上线后第一周**跑 `scripts/breach_rate.py` 观测双向偏差：