agent_9art/AGENTS.md

Agent Instructions for 九艺AI坐席辅助系统

部署规则（核心）

⚠️ 任何代码修改后必须同步服务器部署

无论前端、后台还是后端，任何代码修改完成后，都必须立即同步到服务器并重新部署，绝对不能只做本地修改就结束。

---

一、前端 Sidebar 部署

模块路径: frontend/sidebar/ 服务器部署路径: /www/wwwroot/deploy-package/frontend/sidebar/ 容器名称: ai-assistant-sidebar 访问地址: https://ai.9artedu.com/sidebar/

部署流程

# 1. 本地构建
cd frontend/sidebar && npm run build

# 2. 同步到服务器（注意带 JS hash 的文件名会变化）
scp -r -o StrictHostKeyChecking=no -i root.pem frontend/sidebar/dist/* root@8.133.162.25:/www/wwwroot/deploy-package/frontend/sidebar/dist/

# 3. SSH 登录服务器，更新 index.html 缓存戳并重启容器
ssh -o StrictHostKeyChecking=no -i root.pem root@8.133.162.25 << 'EOF'
cd /www/wwwroot/deploy-package/frontend/sidebar/dist
# 更新 index.html 中的 JS/CSS 引用，带上版本戳防缓存
JS_FILE=$(ls assets/index-*.js | head -1)
CSS_FILE=$(ls assets/index-*.css | head -1)
cat > index.html << HTML
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
    <title>AI坐席助手</title>
    <script src="https://res.wx.qq.com/open/js/jweixin-1.2.0.js"></script>
    <script type="module" crossorigin src="/sidebar/$JS_FILE?v=$(date +%s)"></script>
    <link rel="stylesheet" crossorigin href="/sidebar/$CSS_FILE?v=$(date +%s)">
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>
HTML
# 复制到容器并重启
docker cp . ai-assistant-sidebar:/usr/share/nginx/html/
# 若 frontend/sidebar/nginx.conf 有变更（如新增页面路由），需同步到容器再 reload
docker cp ../nginx.conf ai-assistant-sidebar:/etc/nginx/conf.d/default.conf
docker exec ai-assistant-sidebar nginx -t && docker exec ai-assistant-sidebar nginx -s reload
docker restart ai-assistant-nginx
EOF

多页说明：sidebar 是 Vite 多页应用（vite.config.ts rollupOptions.input）。/sidebar/summary 为每日总结页，/sidebar/summary-search 为运营按手机号/微信号查询客户总结的页面；新增页面时需在 frontend/sidebar/nginx.conf 加对应的精确匹配 location = /xxx { try_files /xxx.html =404; }。

---

二、后台 Admin 部署

模块路径: frontend/admin/ 服务器部署路径: /www/wwwroot/deploy-package/frontend/admin/ 容器名称: ai-assistant-admin 访问地址: https://ai.9artedu.com/admin/

部署流程

# 1. 本地构建
cd frontend/admin && npm run build

# 2. 同步到服务器
scp -r -o StrictHostKeyChecking=no -i root.pem frontend/admin/dist/* root@8.133.162.25:/www/wwwroot/deploy-package/frontend/admin/dist/

# 3. SSH 登录服务器，重新构建镜像并重启容器
ssh -o StrictHostKeyChecking=no -i root.pem root@8.133.162.25 << 'EOF'
cd /www/wwwroot/deploy-package/frontend/admin
docker build -t deploy-package-admin .
docker stop ai-assistant-admin
docker rm ai-assistant-admin
cd /www/wwwroot/deploy-package
docker-compose up -d admin
EOF

---

三、后端微服务部署

模块路径: backend/*-service/ 服务器部署路径: /www/wwwroot/deploy-package/backend/*-service/ 技术栈: Spring Boot + Docker Compose

微服务列表

服务名	容器名	端口	部署路径
gateway	ai-assistant-gateway	8080	backend/gateway/
auth-service	ai-assistant-auth	8081	backend/auth-service/
archive-service	ai-assistant-archive	8082	backend/archive-service/
conversation-service	ai-assistant-conversation	8083	backend/conversation-service/
intent-service	ai-assistant-intent	8084	backend/intent-service/
recommend-service	ai-assistant-recommend	8085	backend/recommendation-service/
generation-service	ai-assistant-generation	8086	backend/generation-service/
kb-admin-service	ai-assistant-kbadmin	8087	backend/kb-admin-service/
analytics-service	ai-assistant-analytics	8088	backend/analytics-service/

部署流程（以某个服务为例）

# 1. 本地构建 JAR 包（通常在对应服务目录下）
cd backend/auth-service && mvn clean package -DskipTests

# 2. 将 JAR 包同步到服务器的 deploy-package 对应目录
scp -o StrictHostKeyChecking=no -i root.pem target/*.jar root@8.133.162.25:/www/wwwroot/deploy-package/backend/auth-service/

# 3. SSH 登录服务器，重新构建镜像并启动容器
# ⚠️ 注意：Dockerfile 中 COPY 的是 app.jar，必须先把新 jar 复制为 app.jar
# ⚠️ docker-compose up 没有 --no-cache 参数，如需无缓存构建应分两步执行
ssh -o StrictHostKeyChecking=no -i root.pem root@8.133.162.25 << 'EOF'
cd /www/wwwroot/deploy-package/backend/auth-service
cp auth-service-*.jar app.jar
cd /www/wwwroot/deploy-package
docker-compose build --no-cache auth-service
docker-compose up -d auth-service
EOF

一键脚本

项目根目录已提供 deploy-archive-service.sh，可自动完成 archive-service 的构建、上传、部署和自检。

---

服务器信息

• IP: 8.133.162.25
• SSH 私钥: root.pem（项目根目录）
• 部署根目录: /www/wwwroot/deploy-package/
• Docker Compose 文件: /www/wwwroot/deploy-package/docker-compose.yml
• 前端站点: https://ai.9artedu.com/sidebar/
• 后台站点: https://ai.9artedu.com/admin/
• 代理: 宝塔 Nginx → Docker Nginx (8089) → 各容器
• 生产数据库: 各微服务连接的是腾讯云 MySQL（MYSQL_HOST/MYSQL_PORT/MYSQL_USERNAME/MYSQL_PASSWORD 见容器 env，库名 ai_assistant），不是服务器上的 ai-assistant-mysql 容器（那是闲置的本地实例）。线上改表结构（ALTER TABLE 等）必须打到腾讯云实例上，可从服务器用 docker exec ai-assistant-mysql mysql -h <云DB地址> ... 执行。