From 6033538cf6f9b9e84176e64ffb97b6600581aa98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Wed, 30 Sep 2026 16:07:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=E6=96=B0=E5=A2=9E=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=B3=A8=E6=84=8F=E4=BA=8B=E9=A1=B9(compose=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=90=8D=E4=BA=92=E5=88=A0=E4=BA=8B=E6=95=85/?= =?UTF-8?q?=E9=9D=99=E6=80=81=E6=96=87=E4=BB=B6build/1Panel=E5=8F=8D?= =?UTF-8?q?=E4=BB=A3/=E5=90=8C=E9=A1=B5=E5=A4=9A=E6=8C=82=E4=BB=B6/?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=B9=B2=E5=87=80)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- CLAUDE.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) 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_`）与 host id + （`cc-widget-host`）**同名互相干扰**——需要同页共存时先给全局命名加项目前缀。 +5. **服务器上不许有未提交改动**：`git status` 应干净；改动请进 git 再部署， + 避免回到 stash 时代（pull 冲突）。 + ## 上线观察期（第一周必做） 上线不是终点。**上线后第一周**跑 `scripts/breach_rate.py` 观测双向偏差：