# 甲辰藏品管理系统 v1.0.1 升级指南

**版本**: v1.0.1  
**发布日期**: 2026-03-16  
**前置版本**: v1.0.0

---

## 🎯 升级内容

### 主要修复

1. **Logo 显示规范化** - 仅在登录页、首页显示
2. **图片代理修复** - Nginx location 优先级调整
3. **后端图片数据加载** - 藏品列表 API 返回图片
4. **前端图片路径修复** - 避免路径重复

---

## 📋 升级步骤

### 方案一：完整升级（推荐）

#### 1. 备份当前版本

```bash
# 备份数据库
sudo -u postgres pg_dump zodiac > /backup/zodiac_v1.0.0.sql

# 备份代码
cp -r /opt/jiachenlong-backend /opt/jiachenlong-backend.backup
```

#### 2. 拉取最新代码

```bash
cd /opt/jiachenlong-backend
git pull origin master
git checkout v1.0.1
```

#### 3. 更新后端

```bash
# 安装依赖（如有更新）
pip3 install -r requirements.txt

# 重启后端服务
pkill -f 'python.*uvicorn'
sleep 2
export DATABASE_URL='postgresql://postgres:postgres@47.98.171.101:5432/zodiac'
nohup /usr/bin/python3.11 -m uvicorn app.main:app --port 3000 --host 0.0.0.0 > /tmp/uvicorn.log 2>&1 &

# 验证服务
sleep 5
curl http://localhost:3000/health
```

#### 4. 更新前端

```bash
# 构建前端
cd /path/to/jiachenlong/frontend
npm install
npm run build

# 部署到前端服务器
scp -r dist/* root@8.149.137.26:/var/www/html/
```

#### 5. 更新 Nginx 配置

```bash
# 复制新配置
scp config/nginx.conf root@8.149.137.26:/etc/nginx/conf.d/jiachenlong.conf

# 重启 Nginx
ssh root@8.149.137.26 "nginx -t && nginx -s reload"
```

#### 6. 验证升级

```bash
# 测试 Logo 显示
curl http://8.149.137.26/ | grep "甲辰收藏"

# 测试图片代理
curl -o /dev/null -w '%{http_code}' http://8.149.137.26/uploads/collections/admin-0001-J051963351.jpeg

# 测试 API
TOKEN=$(curl -s -X POST http://47.110.37.129:3000/api/auth/login -d 'username=admin&password=admin123' | grep -oP '"access_token":\s*"\K[^"]+')
curl -s -H "Authorization: Bearer $TOKEN" http://47.110.37.129:3000/api/collections?limit=1 | python3 -c "import sys,json; d=json.load(sys.stdin); print('图片数:', len(d.get('data',[{}])[0].get('images',[])))"
```

---

### 方案二：快速升级（仅修复图片问题）

#### 1. 仅更新 Nginx 配置

```bash
# 复制 Nginx 配置
scp config/nginx.conf root@8.149.137.26:/etc/nginx/conf.d/jiachenlong.conf

# 重启 Nginx
ssh root@8.149.137.26 "nginx -t && nginx -s reload"
```

#### 2. 仅更新后端代码

```bash
# 更新 collections.py
scp backend/app/routers/collections.py root@47.110.37.129:/opt/jiachenlong-backend/app/routers/

# 重启后端
ssh root@47.110.37.129 "pkill -f uvicorn && sleep 2 && export DATABASE_URL='postgresql://postgres:postgres@47.98.171.101:5432/zodiac' && cd /opt/jiachenlong-backend && nohup /usr/bin/python3.11 -m uvicorn app.main:app --port 3000 --host 0.0.0.0 > /tmp/uvicorn.log 2>&1 &"
```

#### 3. 仅更新前端代码

```bash
# 构建并部署
cd frontend
npm run build
scp -r dist/* root@8.149.137.26:/var/www/html/
```

---

## 🔍 验证清单

### Logo 显示
- [ ] 登录页面显示 Logo
- [ ] 首页显示 Logo
- [ ] 藏品详情页无图片时显示"无图片"
- [ ] Logo 不替代缺失的藏品图片

### 图片功能
- [ ] 藏品列表显示缩略图
- [ ] 藏品详情显示大图
- [ ] 图片预览弹窗正常
- [ ] 图片切换功能正常
- [ ] 后端图片代理正常（HTTP 200）

### API 接口
- [ ] GET /api/collections 返回图片数据
- [ ] GET /api/collections/:id 返回图片详情
- [ ] GET /uploads/collections/xxx.jpg 返回 200

---

## ⚠️ 注意事项

### 升级前
1. ✅ 备份数据库
2. ✅ 备份代码
3. ✅ 通知用户系统维护

### 升级中
1. ✅ 按顺序执行步骤
2. ✅ 每步验证成功再继续
3. ✅ 记录遇到的问题

### 升级后
1. ✅ 验证所有功能
2. ✅ 检查错误日志
3. ✅ 监控系统性能

---

## 🐛 回滚方案

### 回滚到 v1.0.0

```bash
# 回滚代码
cd /opt/jiachenlong-backend
git checkout v1.0.0

# 恢复 Nginx 配置
ssh root@8.149.137.26 "cp /etc/nginx/conf.d/jiachenlong.conf.backup /etc/nginx/conf.d/jiachenlong.conf && nginx -s reload"

# 重启服务
pkill -f uvicorn
cd /opt/jiachenlong-backend
nohup /usr/bin/python3.11 -m uvicorn app.main:app --port 3000 --host 0.0.0.0 &
```

---

## 📞 技术支持

- **代码仓库**: http://47.253.189.47:3000/coolbot/jiachenlong
- **版本标签**: v1.0.1
- **相关文档**: 
  - `docs/RELEASE_v1.0.1.md` - 发布说明
  - `docs/IMAGE_PROCESSING_FLOW.md` - 图片处理流程
  - `docs/DEPLOYMENT_COMPLETE_v1.0.1.md` - 部署报告

---

**升级完成！系统运行正常！** 🎉

**甲辰藏品管理系统开发团队**  
2026-03-16