jiachenlong/docs/DEPLOYMENT.md

# 🐉 甲辰藏品管理系统 环境部署手册

> **版本**: v1.0  
> **更新日期**: 2026-04-24  
> **维护人**: 龙大

---

## 📋 环境总览

| 环境 | 定位 | 域名 | 前端IP | 后端IP | 数据库 | 状态 |
|------|------|------|--------|--------|--------|------|
| **C** | 测试开发 | socoolbot.com.cn | 47.103.29.111 | 47.103.9.192:3000 | 本地PostgreSQL | ✅ 开放 |
| **A** | 灰度发布 | socoolbot.com | 120.26.133.10 | 120.26.144.208:3000 | RDS | 🔒 封闭 |
| **B** | 主系统(生产) | jiachenlong.com | 120.55.81.21 | 47.110.37.129:3000 | RDS | 🔒 封闭 |
| **D** | 备用环境 | socoolbot.cn | 47.111.184.210 | 47.111.184.210:3000 | RDS | 🔒 封闭 |

### 部署流程
```
开发(C) → 灰度(A测试) → 主系统(B发布) → 备用(D保留)
```

---

## ⚠️ 绝对准则

1. **环境操作准则**：A、B环境的系统更新和操作必须经过酷博特允许，否则绝对不允许操作
2. **版本管理准则**：版本管理必须经过酷博特确认，不许擅自更新版本号
3. **数据操作准则**：RDS数据库中的数据，没有酷博特允许，不许进行增删改的操作
4. **操作原则**：以上三条为绝对准则，任何情况下都不得违反

---

## 🧪 C环境（测试开发环境）

### 特点
- **用途**：开发测试，所有新功能先在这里开发测试
- **数据库**：本地PostgreSQL，不连接RDS
- **权限**：开放，可自行操作
- **网络**：可直接访问公网

### 服务器信息

| 角色 | IP | SSH密码 | 服务 |
|------|-----|---------|------|
| 前端 | 47.103.29.111 | Test1234 | Nginx + React构建产物 |
| 后端 | 47.103.9.192 | Test1234 | FastAPI + 本地PostgreSQL |

### 访问链接
- 前端：http://47.103.29.111
- API：http://47.103.9.192:3000

### 部署步骤

#### 前端部署
```bash
# 1. 本地构建
cd /root/.openclaw/workspace/jiachenlong/frontend
npm run build

# 2. 复制到服务器
sshpass -p 'Test1234' scp -o StrictHostKeyChecking=no \
  /root/.openclaw/workspace/jiachenlong/frontend/dist/* \
  root@47.103.29.111:/var/www/frontend/

# 3. 验证
curl -s http://47.103.29.111/ | grep -o 'index-[^"]*\.js'
```

#### 后端部署
```bash
# 1. 同步代码
sshpass -p 'Test1234' scp -o StrictHostKeyChecking=no \
  -r /root/.openclaw/workspace/jiachenlong/backend \
  root@47.103.9.192:/root/jiachenlong/

# 2. 启动服务（C环境使用本地数据库，不设置DATABASE_URL）
sshpass -p 'Test1234' ssh -o StrictHostKeyChecking=no root@47.103.9.192 \
  'cd /root/jiachenlong/backend && \
   export SECRET_KEY="dev-secret-key-12345" && \
   export OSS_ACCESS_KEY_ID="LTAI5t6HUnpFBLEK9194kPVG" && \
   export OSS_ACCESS_KEY_SECRET="LEr4Q8yRxb8D5b24cKfCwlt4MMoke1" && \
   pkill -f uvicorn 2>/dev/null; \
   sleep 1; \
   nohup python3 -m uvicorn app.main:app --host 0.0.0.0 --port 3000 > /tmp/uvicorn.log 2>&1 &'

# 3. 验证
curl -s http://47.103.9.192:3000/
```

### 部署后检查

```bash
# 1. 前端访问
curl -s -o /dev/null -w "前端: %{http_code}" http://47.103.29.111/

# 2. 后端API
curl -s -o /dev/null -w "后端: %{http_code}" http://47.103.9.192:3000/

# 3. 登录功能
curl -s -X POST http://47.103.9.192:3000/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123" | grep -q "token" && echo "登录OK"

# 4. 列表加载速度（应<1秒）
time curl -s "http://47.103.9.192:3000/api/seek/list?page=1&page_size=500" -o /dev/null
```

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 前端显示旧版本 | 浏览器缓存 | Ctrl+F5 强制刷新 |
| 后端启动失败 | 环境变量未设置 | 检查 start_backend.sh 脚本 |
| 数据库连接失败 | 使用了RDS地址 | C环境不使用DATABASE_URL环境变量 |
| 加载很慢 | seek列表计算网络匹配 | 检查seek.py是否移除了match_collections_count_from_coolbot |

---

## 🏭 A环境（灰度发布环境）

### 特点
- **用途**：发布前测试验证
- **数据库**：阿里云RDS (pgm-bp1t5w248t7s1pvr)
- **权限**：🔒 封闭，需酷博特授权
- **域名**：socoolbot.com

### 服务器信息

| 角色 | IP | 内网IP | SSH密码 |
|------|-----|--------|---------|
| WebA | 120.26.133.10 | 172.26.29.103 | AJiachen123 |
| AppA | 120.26.144.208 | 172.26.30.31 | AJiachen123 |

### 访问链接
- https://socoolbot.com

### 短信配置
- 签名：苏州双人旁
- 模板：SMS_505015231
- AccessKey：LTAI5t86bc1nNKVNyYv4Af6x

### 部署步骤（需授权）

#### 部署前准备
1. 确认要部署的版本
2. 联系酷博特获取授权
3. 确认数据库密码

#### 第一步：前端部署
```bash
# SSH连接
ssh root@120.26.133.10  # 密码: AJiachen123

# 克隆代码
cd /root && rm -rf jiachenlong
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git

# 构建
cd /root/jiachenlong/frontend && npm install && npm run build

# 复制到Nginx目录
rm -rf /var/www/frontend/*
cp -r /root/jiachenlong/frontend/dist/* /var/www/frontend/

# 复制Logo
mkdir -p /var/www/frontend/static/images
cp /root/jiachenlong/static/images/jiachenlong-logo.png /var/www/frontend/static/images/

# 复制用户协议
cp /root/jiachenlong/frontend/dist/user_agreement.html /var/www/frontend/

# 重启Nginx
nginx -s reload
```

#### 第二步：后端部署
```bash
# SSH连接
ssh root@120.26.144.208  # 密码: AJiachen123

# 克隆代码
cd /root && rm -rf jiachenlong
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git

# 安装依赖
cd /root/jiachenlong/backend && pip3 install -r requirements.txt

# 创建启动脚本
cat > /root/jiachenlong/start.sh << 'EOF'
#!/bin/bash
cd /root/jiachenlong/backend
export DATABASE_URL="postgresql://jiachenlong:Passwd1%403@pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com:5432/jiachenlong"
export SECRET_KEY="production-secret-key-a-env"
export OSS_ACCESS_KEY_ID="LTAI5t6HUnpFBLEK9194kPVG"
export OSS_ACCESS_KEY_SECRET="LEr4Q8yRxb8D5b24cKfCwlt4MMoke1"
export SMS_ACCESS_KEY_ID="LTAI5t86bc1nNKVNyYv4Af6x"
export SMS_ACCESS_KEY_SECRET="92EVAIE3GECr214c9UaSF6TSYJvDLY"
export SMS_SIGN_NAME="苏州双人旁"
export SMS_TEMPLATE_CODE="SMS_505015231"
nohup python3 -m uvicorn app.main:app --host 0.0.0.0 --port 3000 > /tmp/uvicorn.log 2>&1 &
echo "A环境后端已启动"
EOF

chmod +x /root/jiachenlong/start.sh

# 启动服务
pkill -f uvicorn; sleep 1; /root/jiachenlong/start.sh
```

#### 第三步：验证部署
```bash
# 1. 版本检查
curl -s https://socoolbot.com/ | grep -o 'v[0-9.]*'

# 2. API检查
curl -s -o /dev/null -w "API: %{http_code}" https://socoolbot.com/api/

# 3. 登录测试
curl -s -X POST https://socoolbot.com/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"
```

### 部署后检查清单

- [ ] 前端页面可访问（HTTP和HTTPS）
- [ ] 版本号显示正确
- [ ] 登录功能正常
- [ ] 藏品列表加载正常
- [ ] 藏品新增/编辑功能正常
- [ ] 图片上传功能正常
- [ ] 短信发送功能正常
- [ ] 历史数据完整（用户数、藏品数）

---

## 🏭 B环境（主系统生产环境）

### 特点
- **用途**：主系统生产环境，统一入口
- **数据库**：阿里云RDS (pgm-bp1t5w248t7s1pvr)
- **权限**：🔒 封闭，需酷博特授权
- **域名**：jiachenlong.com

### 服务器信息

| 角色 | IP | 内网IP | SSH密码 |
|------|-----|--------|---------|
| WebB | 120.55.81.21 | 172.26.30.30 | Jiachen123 |
| AppB | 47.110.37.129 | 172.26.29.98 | Jiachen123 |

### 访问链接
- https://jiachenlong.com

### 短信配置
- 签名：双人旁文化传媒
- 模板：SMS_504740243
- AccessKey：LTAI5tPzZDqbM1J6zbk8Wy4q

### 部署步骤（需授权）

#### 第一步：前端部署
```bash
ssh root@120.55.81.21  # 密码: Jiachen123

# 克隆代码并构建（同A环境）
cd /root && rm -rf jiachenlong
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git
cd /root/jiachenlong/frontend && npm install && npm run build

rm -rf /var/www/frontend/*
cp -r /root/jiachenlong/frontend/dist/* /var/www/frontend/
mkdir -p /var/www/frontend/static/images
cp /root/jiachenlong/static/images/jiachenlong-logo.png /var/www/frontend/static/images/
cp /root/jiachenlong/frontend/dist/user_agreement.html /var/www/frontend/
nginx -s reload
```

#### 第二步：后端部署
```bash
ssh root@47.110.37.129  # 密码: Jiachen123

# 克隆代码
cd /root && rm -rf jiachenlong
git clone http://47.253.189.47:3000/coolbot/jiachenlong.git
cd /root/jiachenlong/backend && pip3 install -r requirements.txt

# 创建启动脚本（注意：B环境使用不同的短信配置）
cat > /root/jiachenlong/start.sh << 'EOF'
#!/bin/bash
cd /root/jiachenlong/backend
export DATABASE_URL="postgresql://jiachenlong:Passwd1%403@pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com:5432/jiachenlong"
export SECRET_KEY="production-secret-key-b-env-20260401"
export OSS_ACCESS_KEY_ID="LTAI5t6HUnpFBLEK9194kPVG"
export OSS_ACCESS_KEY_SECRET="LEr4Q8yRxb8D5b24cKfCwlt4MMoke1"
export SMS_ACCESS_KEY_ID="LTAI5tPzZDqbM1J6zbk8Wy4q"
export SMS_ACCESS_KEY_SECRET="ErT3jH9kL2mN5pQ7rS8uV0wX1yZ4aB6c"
export SMS_SIGN_NAME="双人旁文化传媒"
export SMS_TEMPLATE_CODE="SMS_504740243"
nohup python3 -m uvicorn app.main:app --host 0.0.0.0 --port 3000 --workers 1 > /tmp/uvicorn.log 2>&1 &
echo "B环境后端已启动"
EOF

chmod +x /root/jiachenlong/start.sh
pkill -f uvicorn; sleep 1; /root/jiachenlong/start.sh
```

### 部署后检查清单

- [ ] 前端页面可访问（HTTP和HTTPS）
- [ ] 版本号显示正确
- [ ] 登录功能正常
- [ ] 所有功能正常
- [ ] 短信发送正常
- [ ] 数据完整
- [ ] 向酷博特汇报部署完成

---

## 🧪 D环境（备用环境）

### 特点
- **用途**：备用保留
- **数据库**：阿里云RDS
- **权限**：🔒 封闭，需酷博特授权

### 服务器信息

| 角色 | IP | 内网IP | SSH密码 |
|------|-----|--------|---------|
| WebD | 47.111.184.210 | 172.26.30.32 | (同A/B) |
| AppD | 47.111.184.210 | 172.26.30.33 | (同A/B) |

### 访问链接
- http://47.111.184.210
- socoolbot.cn

### 短信配置
- 签名：双人旁文化传媒
- 模板：SMS_504740243

---

## 🔧 常见问题处理

### 1. 前端显示旧版本
```bash
# 原因：浏览器缓存
# 解决：Ctrl+F5 强制刷新，或清理Nginx缓存
```

### 2. 后端启动失败
```bash
# 检查日志
tail -50 /tmp/uvicorn.log

# 常见错误：
# - SECRET_KEY未设置 → 添加环境变量
# - 数据库连接失败 → 检查DATABASE_URL格式（密码需要URL编码）
# - 端口被占用 → pkill -f uvicorn 后重试
```

### 3. 加载很慢（seek列表）
```bash
# 检查seek.py是否移除了match_collections_count_from_coolbot调用
grep -n "network_matched_count" /root/jiachenlong/backend/app/routers/seek.py

# 确认返回的network_matched_count为0
curl -s "http://后端IP:3000/api/seek/list?page=1&page_size=5" | grep network_matched_count
```

### 4. 图片无法上传
```bash
# 检查OSS配置
curl -s http://后端IP:3000/api/collections/test-upload

# 检查Nginx上传大小限制
grep client_max_body_size /etc/nginx/nginx.conf
```

### 5. 短信发送失败
```bash
# 检查环境变量
ssh root@后端IP "env | grep SMS"

# 检查模板代码和签名是否匹配当前环境
```

### 6. 数据库连接超时
```bash
# 检查RDS白名单
# C环境使用本地数据库，不连RDS
# A/B/D环境需要检查安全组是否允许访问RDS
```

---

## 📝 版本管理

### 更新版本流程
1. 修改代码文件头部Version注释
2. 更新config/VERSION.json
3. 更新config/CHANGELOG.md
4. 提交Git
5. 部署后验证

### 版本检查命令
```bash
# 本地
cat /root/.openclaw/workspace/jiachenlong/config/VERSION.json

# 服务器
curl -s http://服务器IP/ | grep -o 'v[0-9.]*'
```

---

## 📞 紧急联系人

- **酷博特**：项目总负责，所有重大操作需汇报
- **龙大**：环境部署负责人

---

## 📝 部署记录模板

```
## 部署记录 - [日期]

### 环境：[A/B/C/D]
### 版本：[v0.0.x]
### 部署人：龙大

#### 部署步骤
1. [步骤1]
2. [步骤2]

#### 检查结果
- [x] 前端OK
- [x] 后端OK
- [x] 登录OK

#### 问题记录
无

#### 汇报状态
已向酷博特汇报
```