jiachenlong/docs/UPGRADE_v1.0.1.md

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

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

---

🎯 升级内容

主要修复

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

---

📋 升级步骤

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

1. 备份当前版本

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

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

2. 拉取最新代码

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

3. 更新后端

# 安装依赖（如有更新）
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. 更新前端

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

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

5. 更新 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"

6. 验证升级

# 测试 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 配置

# 复制 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. 仅更新后端代码

# 更新 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. 仅更新前端代码

# 构建并部署
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

# 回滚代码
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