7.6 KiB

Raw Blame History

甲辰藏品管理系统部署手册

环境概览

服务器信息

环境	前端	后端	SSH密码
D测试环境	114.55.137.168, 172.26.30.32 (内网)	47.111.184.210, 172.26.30.33 (内网)	Jiachend123
101生产环境	47.98.171.101 (80端口)	47.98.171.101:8080	Coolbot123

数据库信息

用途	数据库	地址	端口	用户名	密码
主数据库	jiachenlong	pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com	5432	jiachenlong	Passwd1@3
一尘数据库	coolbot_data	pgm-bp1t1008h019ez6c.pg.rds.aliyuncs.com	5432	coolbot	Coolbot123

OSS存储

Bucket: jiachenlong-oss

部署流程

1. 获取代码

# 克隆仓库
git clone http://caibotd:Caibotd123@101.37.160.219/root/jiachenlong.git

# 切换到目标版本
cd jiachenlong
git checkout v1.2.78  # 或指定版本tag

2. 构建前端

cd frontend
npm install
npm run build

3. 配置后端环境变量

在后端服务器创建 .env 文件：

cat > /root/jiachenlong/backend/.env << 'EOF'
# 主数据库 - jiachenlong
DB_HOST=pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com
DB_PORT=5432
DB_USER=jiachenlong
DB_PASSWORD=Passwd1@3
DB_NAME=jiachenlong

# 一尘数据库 - coolbot_data
YICHEN_DB_HOST=pgm-bp1t1008h019ez6c.pg.rds.aliyuncs.com
YICHEN_DB_PORT=5432
YICHEN_DB_USER=coolbot
YICHEN_DB_PASSWORD=Coolbot123
YICHEN_DB_NAME=coolbot_data

# 应用配置
SECRET_KEY=jiachenlong-production-secret-key-2026
DATABASE_URL=postgresql://jiachenlong:Passwd1%403@pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com:5432/jiachenlong
EOF

注意：密码中的特殊字符 @ 必须URL编码为 %40

4. 上传文件到服务器

# 上传前端
scp -r frontend/dist/* root@47.111.184.210:/var/www/html/

# 上传后端
scp -r backend/app root@47.111.184.210:/root/jiachenlong/backend/

5. 配置Nginx

D测试环境配置示例 (/etc/nginx/nginx.conf)：

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    server {
        listen 80;
        server_name _;
        
        root /var/www/html;
        index index.html;
        
        # 前端静态文件 (SPA)
        location / {
            try_files $uri $uri/ /index.html;
        }
        
        # 静态资源
        location /static {
            alias /var/www/html/static;
            expires 30d;
        }
        
        # API代理到后端
        location /api/ {
            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
        
        # 上传文件代理
        location /uploads/ {
            proxy_pass http://127.0.0.1:3000;
        }
    }
}

6. 启动后端服务

# 激活conda环境
source /opt/conda/etc/profile.d/conda.sh
conda activate py312

# 设置Python路径
export PYTHONPATH=/root/jiachenlong/backend

# 启动后端
cd /root/jiachenlong/backend
nohup python -m uvicorn app.main:app --host 0.0.0.0 --port 3000 > logs/api.log 2>&1 &

7. 重启Nginx

# 测试配置
nginx -t

# 重载配置
nginx -s reload

# 或完全重启
killall nginx
nginx

常见问题与解决方案

1. 后端启动失败：`address already in use`

原因：端口被占用

解决：

# 查看占用进程
fuser 3000/tcp

# 杀死占用进程
fuser -k 3000/tcp

2. 后端启动失败：`ModuleNotFoundError: No module named 'xxx'`

原因：Python依赖缺失

解决：

pip install -r requirements.txt
# 或安装特定依赖
pip install bcrypt passlib python-jose python-multipart email-validator oss2 Pillow

3. API返回500错误：`name 'response' is not defined`

原因：FastAPI函数参数中使用了response: Response = None，但该参数已被废弃或删除

解决：检查并修复 app/routers/*.py 文件中的 response.headers 使用

# 找到类似代码
response.headers['X-Total-Pages'] = str(total_pages)

# 删除这些行（它们不是必需的）

4. 数据库连接失败：`could not translate host name`

原因：主机名未正确解析

解决：确保 .env 中的数据库地址使用完整域名

# 错误
DB_HOST=pgm-bp1t5w248t7s1pvr

# 正确
DB_HOST=pgm-bp1t5w248t7s1pvr.pg.rds.aliyuncs.com

5. 数据库连接失败：密码中特殊字符问题

原因：密码中的 @ 符号导致URL解析错误

解决：URL编码密码

# 密码 Passwd1@3 编码为 Passwd1%403
DATABASE_URL=postgresql://jiachenlong:Passwd1%403@...

6. 前端403 Forbidden

原因：文件权限问题

解决：

chown -R nginx:nginx /var/www/html
chmod -R 755 /var/www/html

7. Nginx配置错误：`server directive is not allowed here`

原因：nginx配置文件放在HTTP块外面

解决：确保server块在http块内部

8. 前端显示旧版本

原因：浏览器缓存

解决：强制刷新 (Ctrl+Shift+R) 或清除缓存

代码修改注意事项

information.py 常见问题

Response参数问题
- 函数签名中的 response: Response = None 会导致 NameError
- 如果不需要修改响应头，应该直接删除这个参数
- 同时删除函数体内使用 response.headers 的代码
处理方法：

# 错误写法
def get_list(response: Response = None):
    response.headers['X-Total'] = '100'  # 会报错

# 正确写法
def get_list():
    # 不使用response.headers，或使用Response参数的正确方式
    pass

collections.py 统计接口

get_current_user 可能返回 None
访问 current_user.role 前必须检查 current_user 是否为 None

# 错误
if current_user.role == "admin":

# 正确
if not current_user or current_user.role != "admin":
    return {"totalCount": 0}

改进建议

1. 环境变量配置

使用 python-dotenv 管理环境变量
生产环境与测试环境配置分离
敏感信息（密码、密钥）使用环境变量而非硬编码

2. 部署脚本化

编写自动化部署脚本 (deploy.sh)
包含数据库迁移步骤
部署前自动备份

3. 健康检查

添加后端 /health 端点
配置监控告警

4. 日志管理

统一日志格式
日志轮转配置
错误日志实时告警

5. 数据库迁移

使用 Alembic 管理数据库版本
编写数据迁移脚本
部署前检查数据库schema是否匹配

6. 代码质量

CI/CD 自动化测试
代码审查流程
部署前在测试环境验证

快速命令参考

# 查看后端进程
ps aux | grep uvicorn | grep -v grep

# 查看后端日志
tail -f /root/jiachenlong/backend/logs/api.log

# 重启后端
pkill -f 'uvicorn app.main:app'
cd /root/jiachenlong/backend
source /opt/conda/etc/profile.d/conda.sh && conda activate py312
export PYTHONPATH=/root/jiachenlong/backend
nohup python -m uvicorn app.main:app --host 0.0.0.0 --port 3000 > logs/api.log 2>&1 &

# 测试API
curl http://localhost:3000/api/collections/stats
curl http://localhost:3000/api/information/list?info_type=seek

# Nginx相关
nginx -t                    # 测试配置
nginx -s reload            # 重载配置
nginx -s stop              # 停止
killall nginx && nginx     # 完全重启

最后更新：2026-04-09

7.6 KiB Raw Blame History Unescape Escape

甲辰藏品管理系统 部署手册