jiachenlong/docs/标准部署流程.md

甲辰藏品管理系统 - 标准部署流程

版本: v1.0
创建时间: 2026-03-21
维护人: 甲辰生产

---

📋 部署前检查清单

1. 获取信息

项目	内容	获取方式
目标服务器IP	如 8.149.137.26	MEMORY.md
SSH密码	如 Jiachen123	询问酷博特
目标版本	如 v1.2.4	Gitea tags
数据库配置	IP/密码/端口	MEMORY.md

2. 环境确认

# 登录目标服务器
ssh root@<目标IP>

# 检查已有配置（不要覆盖！）
cat /root/jiachenlong/config/VERSION
cat /etc/nginx/conf.d/*.conf

---

🚀 标准部署流程

前端部署（所有环境）

# 1. 登录服务器
ssh root@<前端IP>

# 2. 拉取代码（重要：不要覆盖已有目录）
cd /root
rm -rf jiachenlong_bak
mv jiachenlong jiachenlong_bak  # 备份旧代码
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git jiachenlong

# 3. 检查并修改VERSION文件（重要：用sed保留原内容）
# 先查看原内容
cat jiachenlong/config/VERSION
# 修改VERSION行（保留其他行）
sed -i 's/^VERSION=.*/VERSION=1.2.4/' jiachenlong/config/VERSION

# 4. 构建前端
cd jiachenlong/frontend
npm install
npm run build

# 5. 部署（两个目录都要部署！）
rm -rf /var/www/mobile/*
rm -rf /var/www/frontend/*
cp -r dist/* /var/www/mobile/
cp -r dist/* /var/www/frontend/
cp -r ../static /var/www/mobile/
cp -r ../static /var/www/frontend/

# 6. 部署用户协议（如有）
cp user_agreement.html /var/www/mobile/
cp user_agreement.html /var/www/frontend/

# 7. 重载Nginx
nginx -s reload

后端部署（所有环境）

# 1. 登录服务器
ssh root@<后端IP>

# 2. 拉取代码
cd /root
rm -rf jiachenlong_bak
mv jiachenlong jiachenlong_bak
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git jiachenlong

# 3. 检查OCR扩展名修复（如无则手动修复）
grep -n 'temp_extensions' jiachenlong/backend/app/routers/ocr.py
# 如只有小写，修复：
sed -i "s/temp_extensions = \['jpg', 'jpeg', 'png', 'gif'\]/temp_extensions = ['jpg', 'jpeg', 'png', 'gif', 'JPG', 'JPEG', 'PNG', 'GIF']/" jiachenlong/backend/app/routers/ocr.py

# 4. 检查数据库配置
cat jiachenlong/backend/.env | grep DATABASE_URL

# 5. 停止旧服务
pkill -f uvicorn

# 6. 启动新服务
cd jiachenlong/backend
nohup python3 -m uvicorn app.main:app --host 0.0.0.0 --port 3000 > /tmp/uvicorn.log 2>&1 &

# 7. 等待启动
sleep 5

# 8. 验证
curl -s http://localhost:3000/ | head -c 100

---

✅ 部署后验证清单

必须验证的项目

#	验证项	命令	期望结果
1	前端页面	curl http://<前端IP>/	200 + HTML
2	前端版本	curl http://<前端IP>/ | grep title	v1.2.4
3	前端端口	curl http://<前端IP>:3001/	200
4	后端健康	curl http://<后端IP>:3000/	200
5	登录功能	curl -X POST http://<后端IP>:3000/api/auth/login -d "username=admin&password=admin123"	返回token
6	Logo图片	curl -I http://<前端IP>/static/images/jiachenlong-logo.png	200
7	用户协议	curl http://<前端IP>/user_agreement.html	200 + 内容
8	80端口	curl -o /dev/null -w "%{http_code}" http://<前端IP>/	200
9	API代理	curl http://<前端IP>/api/collections	JSON响应

与基准环境对比

# 以C环境为基准，对比关键文件
# C环境
curl -s http://47.103.29.111/ | grep title
# B环境  
curl -s http://8.149.137.26/ | grep title
# 期望：版本号一致

---

⚠️ 常见错误及解决方案

1. git clone失败（目录已存在）

错误：

fatal: destination path . already exists and is not an empty directory.

解决：

# 方法1：先备份再删除
mv jiachenlong jiachenlong_backup
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git

# 方法2：删除后克隆
rm -rf jiachenlong
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git

2. VERSION文件被覆盖

错误：

VERSION=1.2.4
# 原有内容丢失

解决：使用sed修改而非echo覆盖

# 错误方法
echo "VERSION=1.2.4" > VERSION  # ❌ 会覆盖整个文件

# 正确方法
sed -i s/^VERSION=.*/VERSION=1.2.4/ VERSION  # ✅ 只修改VERSION行

3. 版本号显示vv1.2.4

原因：VERSION文件带v前缀 + vite.config.js又加v

解决：

# VERSION文件不要带v
VERSION=1.2.4  # ✅
# 不是 VERSION=v1.2.4

# 源index.html如有vv先修复
sed -i s/vv/v/g index.html

4. 首页Logo显示404

原因：static目录未部署

解决：

# 部署时必须复制static目录
cp -r ../static /var/www/mobile/
cp -r ../static /var/www/frontend/

5. 浏览器缓存旧JS

原因：JS文件名hash未变

解决：首页Logo添加版本号

// Home.jsx
<img src="/static/images/jiachenlong-logo.png?v=1.2.4" ... />

6. Nginx 80端口返回403

原因：root目录为空或不存在

解决：

# 检查目录
ls -la /var/www/frontend/

# 部署到正确目录
cp -r dist/* /var/www/frontend/

# 重载Nginx
nginx -s reload

---

📊 环境配置参考

A环境（生产）

服务	IP	端口
前端	8.154.46.3	80, 3001
后端	42.121.116.25	3000
数据库	47.98.171.101	5432

B环境（灰度）

服务	IP	端口
前端	8.149.137.26	80, 3001
后端	47.110.37.129	3000
数据库	47.96.181.36	5432

C环境（测试）

服务	IP	端口
前端	47.103.29.111	80
后端	47.103.9.192	3000
数据库	47.103.9.192	5432

---

📝 部署记录模板

每次部署后填写：

## 部署记录

### 2026-03-21 v1.2.4

| 环境 | 部署时间 | 操作人 | 结果 |
|------|---------|--------|------|
| B环境 | 00:27 | 甲辰生产 | ✅ 成功 |

### 部署命令
```bash
# 前端
ssh root@8.149.137.26
cd /root/jiachenlong/frontend
npm run build
cp -r dist/* /var/www/mobile/
cp -r dist/* /var/www/frontend/

# 后端
ssh root@47.110.37.129
pkill -f uvicorn
cd /root/jiachenlong/backend
nohup python3 -m uvicorn app.main:app --host 0.0.0.0 --port 3000 &

验证结果

• 前端版本：v1.2.4 ✅
• 后端健康：200 ✅
• Logo显示：200 ✅

问题记录

无

---

**文档结束**