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

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

---

## 📋 部署前检查清单

### 1. 获取信息

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

### 2. 环境确认

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

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

---

## 🚀 标准部署流程

### 前端部署（所有环境）

```bash
# 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
```

### 后端部署（所有环境）

```bash
# 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响应 |

### 与基准环境对比

```bash
# 以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.
```

**解决**：
```bash
# 方法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覆盖
```bash
# 错误方法
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

**解决**：
```bash
# 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目录未部署

**解决**：
```bash
# 部署时必须复制static目录
cp -r ../static /var/www/mobile/
cp -r ../static /var/www/frontend/
```

### 5. 浏览器缓存旧JS

**原因**：JS文件名hash未变

**解决**：首页Logo添加版本号
```jsx
// Home.jsx
<img src="/static/images/jiachenlong-logo.png?v=1.2.4" ... />
```

### 6. Nginx 80端口返回403

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

**解决**：
```bash
# 检查目录
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 |

---

## 📝 部署记录模板

每次部署后填写：

```markdown
## 部署记录

### 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 ✅

### 问题记录
无
```

---

**文档结束**