# 甲辰藏品管理系统 - 测试环境部署手册 **版本**: v2.7.9 **创建时间**: 2026-03-15 **创建人**: 菜鸟小 D (开发程序员助理) **文档状态**: ✅ 完整可用 **最后更新**: 2026-03-15 (实地检查后更新) --- ## ⚠️ 重要说明 ### 🎯 v2.7.9 标准技术栈 **本文档描述的是甲辰藏品管理系统 v2.7.9 的标准部署方案。** | 组件 | v2.7.9 技术栈 | |------|-------------| | **前端** | React 18 + Vite 6 + Tailwind CSS | | **后端** | FastAPI 0.109 + Python 3.12 | | **数据库** | PostgreSQL 13+ | | **ORM** | SQLAlchemy 2.0 + Alembic | | **认证** | JWT (python-jose) | | **Web 服务器** | Nginx 1.20+ | | **监控** | Prometheus (可选) | ### 📦 v2.7.9 核心依赖 **后端 (backend-fastapi/requirements.txt)**: ``` fastapi==0.109.0 uvicorn[standard]==0.27.0 sqlalchemy==2.0.25 asyncpg==0.29.0 python-jose[cryptography]==3.3.0 passlib[bcrypt]==1.7.4 pydantic==2.5.3 ``` **前端 (zodiac-mobile/package.json)**: ``` react@18 vite@6 tailwindcss@3 ``` --- ### ⚠️ 测试环境现状（2026-03-15 检查） **当前测试环境与 v2.7.9 标准不符！** | 项目 | v2.7.9 标准 | 测试环境现状 | 状态 | |------|-----------|------------|------| | 后端框架 | FastAPI + Python | Node.js + Express | ❌ 不符 | | ORM | SQLAlchemy | Prisma | ❌ 不符 | | 数据库 | PostgreSQL | PostgreSQL | ✅ 符合 | | 前端 | React + Vite | React + Vite | ✅ 符合 | **需要重新部署测试环境以匹配 v2.7.9 标准！** --- ## 更新日志 | 版本 | 日期 | 更新人 | 更新内容 | |------|------|--------|---------| | v1.2 | 2026-03-15 | 菜鸟小 D | 添加详细版本要求和关键注意事项 | | v1.1 | 2026-03-15 | 菜鸟小 D | 根据实地检查更新实际配置 | | v1.0 | 2026-03-15 | 菜鸟小 D | 初始版本 | --- ## 🔧 系统要求（v2.7.9 标准） ### ⚙️ 操作系统要求 | 服务器 | 操作系统 | 版本要求 | |--------|---------|---------| | 菜鸟测试 1 | Alibaba Cloud Linux | 3.x (OpenAnolis) | | 菜鸟测试 2 | Alibaba Cloud Linux | 3.x (OpenAnolis) | **替代方案**: CentOS 7+ / Ubuntu 20.04+ / Rocky Linux 8+ --- ### 🖥️ 服务器配置要求 | 服务器 | CPU | 内存 | 磁盘 | 用途 | |--------|-----|------|------|------| | 菜鸟测试 1 | 2 核 + | 4GB+ | 40GB+ | Nginx + Prometheus + 前端 | | 菜鸟测试 2 | 4 核 + | 8GB+ | 50GB+ SSD | FastAPI 后端 + PostgreSQL | --- ### 📦 前端技术栈（v2.7.9） | 组件 | 版本 | 说明 | |------|------|------| | **React** | 18.x | UI 框架 | | **Vite** | 6.x | 构建工具 | | **Tailwind CSS** | 3.x | CSS 框架 | | **Node.js** | 18.x+ | 运行时环境 | | **npm** | 9.x+ | 包管理器 | **构建命令**: ```bash cd zodiac-mobile npm install npm run build ``` **部署路径**: `/var/www/mobile/dist` --- ### 🐍 后端技术栈（v2.7.9） | 组件 | 版本 | 说明 | |------|------|------| | **FastAPI** | 0.109.0 | Web 框架 | | **Python** | 3.12.x | 运行时环境 | | **Uvicorn** | 0.27.0 | ASGI 服务器 | | **SQLAlchemy** | 2.0.25 | ORM 框架 | | **Alembic** | 1.13.1 | 数据库迁移 | | **Pydantic** | 2.5.3 | 数据验证 | | **python-jose** | 3.3.0 | JWT 认证 | | **passlib** | 1.7.4 | 密码加密 | | **asyncpg** | 0.29.0 | PostgreSQL 驱动 | **完整依赖** (`backend-fastapi/requirements.txt`): ``` fastapi==0.109.0 uvicorn[standard]==0.27.0 sqlalchemy==2.0.25 asyncpg==0.29.0 python-jose[cryptography]==3.3.0 passlib[bcrypt]==1.7.4 python-multipart==0.0.6 pydantic==2.5.3 pydantic[email]==2.5.3 python-dotenv==1.0.0 alembic==1.13.1 requests ``` **安装命令**: ```bash pip3.12 install -r requirements.txt ``` **启动命令**: ```bash uvicorn app.main:app --port 3000 --host 0.0.0.0 ``` --- ### 🗄️ 数据库要求 | 组件 | 版本 | 说明 | |------|------|------| | **PostgreSQL** | 13.x+ | 关系型数据库 | | **psql** | 13.x+ | 命令行工具 | **数据库配置**: ``` 数据库名：zodiac 用户名：postgres 密码：postgres (生产环境请使用强密码) 端口：5432 ``` --- ### 🌐 Web 服务器要求 | 组件 | 版本 | 说明 | |------|------|------| | **Nginx** | 1.20.x+ | Web 服务器/反向代理 | **Nginx 配置要求**: - 监听端口：3001 (前端) - API 代理：/api → http://127.0.0.1:3000/api - 文件上传限制：20MB (**必须配置 client_max_body_size**) - SPA 路由支持：try_files **Nginx 配置示例** (`/etc/nginx/conf.d/zodiac.conf`): ```nginx server { listen 3001; server_name _; root /var/www/mobile/dist; index index.html; # ⚠️ 必须配置：允许上传最大 20MB 的文件 client_max_body_size 20M; location / { try_files $uri $uri/ /index.html; } location /api { proxy_pass http://127.0.0.1:3000/api; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # ⚠️ API 上传也要配置限制 client_max_body_size 20M; } } ``` **⚠️ 重要**: 如果不配置 `client_max_body_size`，Nginx 默认限制为 **1MB**，会导致图片上传失败！ --- ### 🔧 其他工具要求 | 工具 | 版本 | 用途 | |------|------|------| | **Git** | 2.x+ | 版本控制 | | **systemd** | 最新 | 服务管理 | | **firewalld** | 最新 | 防火墙管理 | | **Prometheus** | 2.45.x+ | 监控（可选） | --- ## 🚨 部署注意事项（必读） ### ⚠️ 部署前必须完成的配置 #### 1. 阿里云 OCR API Key 配置 **获取 API Key**: ``` 1. 访问：https://dashscope.console.aliyun.com/apiKey 2. 登录阿里云账号 3. 创建/复制 API Key 4. 更新 .env 配置 ``` **编辑 .env 文件**: ```bash cd /opt/zodiac/backend/backend-fastapi vi .env ``` **.env 内容**: ```ini # ⚠️ 必须配置：阿里云 DashScope OCR API # ⚠️ 注意：不要使用示例 Key，必须替换为您自己的 DASHSCOPE_API_KEY=sk-your-actual-api-key-here # OCR 配置 OCR_MODEL=qwen-vl-max OCR_TIMEOUT=60 ``` **验证 API Key**: ```bash curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer sk-your-actual-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-vl-max", "input": { "messages": [{ "role": "user", "content": [{"type": "text", "text": "你好"}] }] } }' # 成功：{"output": {"choices": [...]}} # 失败：{"error": {"message": "..."}} ``` --- #### 2. Nginx 图片上传限制 **⚠️ 必须配置**，否则会导致： - 图片上传失败（413 错误） - OCR 识别失败（图片太大） - 前端收到 HTML 错误页面而不是 JSON **编辑 Nginx 配置**: ```bash sudo vi /etc/nginx/conf.d/zodiac.conf ``` **添加配置**: ```nginx server { listen 3001; # ⚠️ 必须配置：允许上传 20MB 文件 client_max_body_size 20M; location /api { proxy_pass http://127.0.0.1:3000/api; # ⚠️ API 上传也要配置 client_max_body_size 20M; } } ``` **重启服务**: ```bash sudo nginx -t && sudo nginx -s reload sudo systemctl restart zodiac-backend ``` --- ## ⚠️ 关键注意事项 ### 1. 测试环境必须完全按照 v2.7.9 标准 **当前测试环境问题** (2026-03-15 检查): | 组件 | v2.7.9 标准 | 测试环境现状 | 状态 | |------|-----------|------------|------| | **后端框架** | FastAPI 0.109 + Python 3.12 | Node.js + Express | ❌ **严重不符** | | **ORM** | SQLAlchemy 2.0 | Prisma | ❌ **严重不符** | | **数据库** | PostgreSQL 13 | PostgreSQL 13 | ✅ 符合 | | **前端** | React 18 + Vite 6 | React 18 + Vite 6 | ✅ 符合 | | **操作系统** | Alibaba Cloud Linux 3 | Alibaba Cloud Linux 3 | ✅ 符合 | **结论**: 测试环境后端需要**完全重新部署**，使用 FastAPI 替代 Node.js！ --- ### 2. 版本兼容性要求 - ❌ **不能使用** Node.js 后端（测试环境当前版本） - ❌ **不能使用** Prisma ORM - ✅ **必须使用** FastAPI 0.109.0 - ✅ **必须使用** SQLAlchemy 2.0.25 - ✅ **必须使用** Python 3.12.x --- ### 3. 部署顺序 ``` 1. 准备服务器 (Alibaba Cloud Linux 3) ↓ 2. 安装系统依赖 (Python 3.12, PostgreSQL 13, Nginx 1.20) ↓ 3. 配置数据库 (创建 zodiac 数据库) ↓ 4. 部署后端 (FastAPI + SQLAlchemy) ↓ 5. 部署前端 (React + Vite 构建) ↓ 6. 配置 Nginx (反向代理) ↓ 7. 验证测试 (功能测试清单) ``` --- ### 4. 重要提醒 ⚠️ **测试环境是用于验证 v2.7.9 版本的环境，必须与生产环境保持一致！** - ✅ 所有软件版本必须与 v2.7.9 要求一致 - ✅ 所有配置必须按照本文档说明 - ✅ 所有功能必须通过测试清单验证 - ❌ 不能使用旧版本技术栈（如 Node.js 后端） --- ## 📋 目录 1. [环境概述](#环境概述) 2. [服务器信息](#服务器信息) 3. [部署前准备](#部署前准备) 4. [数据库服务器部署 (菜鸟测试 2)](#数据库服务器部署) 5. [应用服务器部署 (菜鸟测试 1)](#应用服务器部署) 6. [Nginx 配置](#nginx 配置) 7. [Prometheus 监控配置](#prometheus 监控配置) 8. [部署验证与测试](#部署验证与测试) 9. [常见问题与解决方案](#常见问题与解决方案) 10. [维护与监控](#维护与监控) --- ## 环境概述 ### 架构设计 ``` ┌─────────────────┐ ┌─────────────────┐ │ 菜鸟测试 1 │ │ 菜鸟测试 2 │ │ 47.103.29.111 │ │ 47.103.9.192 │ ├─────────────────┤ ├─────────────────┤ │ Nginx (3001) │ ──────▶ │ FastAPI (3000) │ │ Prometheus │ │ PostgreSQL (5432)│ │ 前端静态文件 │ │ 数据库 │ └─────────────────┘ └─────────────────┘ ▲ │ 用户访问 http://47.103.29.111:3001/ ``` ### 版本信息 | 组件 | 版本 | 说明 | |------|------|------| | 甲辰系统 | v2.7.9 | 综合功能增强版 | | Git 分支 | `v2.7.9` | 稳定分支 | | Git 标签 | `v2.7.9-release` | 发布标签 | --- ## 服务器信息 ### 菜鸟测试 1 (应用服务器) | 项目 | 信息 | |------|------| | **名称** | 菜鸟测试 1 | | **IP 地址** | 47.103.29.111 | | **用途** | Nginx + Prometheus 监控 + 前端静态文件 | | **开放端口** | 3001 (前端), 9090 (Prometheus) | | **系统** | CentOS 7+ / Ubuntu 20.04+ | ### 菜鸟测试 2 (数据库服务器) | 项目 | 信息 | |------|------| | **名称** | 菜鸟测试 2 | | **IP 地址** | 47.103.9.192 | | **用途** | FastAPI 后端 + PostgreSQL 数据库 | | **开放端口** | 3000 (后端 API), 5432 (PostgreSQL) | | **系统** | CentOS 7+ / Ubuntu 20.04+ | --- ## 部署前准备 ### 1. 系统要求 #### 菜鸟测试 1 (应用服务器) - **CPU**: 2 核+ - **内存**: 4GB+ - **磁盘**: 20GB+ - **系统**: CentOS 7+ 或 Ubuntu 20.04+ #### 菜鸟测试 2 (数据库服务器) - **CPU**: 4 核+ - **内存**: 8GB+ - **磁盘**: 50GB+ SSD - **系统**: CentOS 7+ 或 Ubuntu 20.04+ ### 2. 软件依赖 #### 菜鸟测试 1 需要安装 ```bash # Nginx sudo yum install nginx -y # CentOS # 或 sudo apt install nginx -y # Ubuntu # Node.js 18+ curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - # CentOS sudo yum install -y nodejs # Prometheus (可选) wget https://github.com/prometheus/prometheus/releases/download/v2.45.0/prometheus-2.45.0.linux-amd64.tar.gz tar xvfz prometheus-*.tar.gz ``` #### 菜鸟测试 2 需要安装 ```bash # Python 3.12 sudo yum install python3.12 -y # CentOS # 或 sudo apt install python3.12 -y # Ubuntu # PostgreSQL 13+ sudo yum install postgresql13-server postgresql13 -y # CentOS # 或 sudo apt install postgresql-13 -y # Ubuntu # Git sudo yum install git -y ``` ### 3. 网络配置 #### 开放端口 ```bash # 菜鸟测试 1 firewall-cmd --permanent --add-port=3001/tcp # 前端 firewall-cmd --permanent --add-port=9090/tcp # Prometheus firewall-cmd --reload # 菜鸟测试 2 firewall-cmd --permanent --add-port=3000/tcp # 后端 API firewall-cmd --permanent --add-port=5432/tcp # PostgreSQL firewall-cmd --reload ``` #### 安全组配置 (阿里云) - 菜鸟测试 1: 开放 3001, 9090 端口 - 菜鸟测试 2: 开放 3000, 5432 端口 (建议限制访问 IP) --- ## 数据库服务器部署 (菜鸟测试 2) ### 1. PostgreSQL 配置 ```bash # 初始化数据库 (如未初始化) sudo postgresql-setup --initdb # CentOS # 或 sudo pg_createcluster 13 main --start # Ubuntu # 启动 PostgreSQL sudo systemctl start postgresql sudo systemctl enable postgresql # 创建数据库和用户 sudo -u postgres psql ``` ```sql -- 创建数据库 CREATE DATABASE zodiac; -- 创建用户 (生产环境请使用强密码) CREATE USER postgres WITH PASSWORD 'postgres' SUPERUSER; -- 授权 GRANT ALL PRIVILEGES ON DATABASE zodiac TO postgres; -- 退出 \q ``` ### 2. 配置远程访问 ```bash # 编辑 pg_hba.conf sudo vi /var/lib/pgsql/data/pg_hba.conf # CentOS # 或 sudo vi /etc/postgresql/13/main/pg_hba.conf # Ubuntu # 添加 (允许菜鸟测试 1 访问) host zodiac postgres 47.103.29.111/32 md5 ``` ```bash # 编辑 postgresql.conf sudo vi /var/lib/pgsql/data/postgresql.conf # 修改 listen_addresses = '*' port = 5432 ``` ```bash # 重启 PostgreSQL sudo systemctl restart postgresql ``` ### 3. 部署 FastAPI 后端 ```bash # 创建部署目录 sudo mkdir -p /opt/zodiac/backend sudo chown -R $USER:$USER /opt/zodiac/backend # 克隆代码 cd /opt/zodiac/backend git clone http://47.253.189.47:3000/coolbot/zodiac-collector.git . git checkout v2.7.9 # 安装 Python 依赖 cd backend-fastapi pip3.12 install -r requirements.txt # 创建环境变量文件 cat > .env << EOF # 生产环境配置 # 数据库配置 (PostgreSQL) DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zodiac # JWT 配置 (生产环境请修改为强密钥) SECRET_KEY=your-production-secret-key-change-this ACCESS_TOKEN_EXPIRE_MINUTES=60 # 服务器配置 PORT=3000 HOST=0.0.0.0 # 阿里云 DashScope OCR API # ⚠️ 注意：需要替换为您自己的 API Key # 获取方式：https://dashscope.console.aliyun.com/apiKey DASHSCOPE_API_KEY=sk-9389024a37da4f7bb455ac9a6b28776f # OCR 配置 OCR_MODEL=qwen-vl-max OCR_TIMEOUT=60 # 文件上传配置 UPLOAD_DIR=./uploads MAX_UPLOAD_SIZE=10485760 EOF # 创建上传目录 mkdir -p uploads chmod 755 uploads ``` ### 4. 创建系统服务 ```bash # 创建 systemd 服务文件 sudo vi /etc/systemd/system/zodiac-backend.service ``` ```ini [Unit] Description=甲辰藏品管理系统后端服务 After=network.target postgresql.service [Service] Type=simple User=postgres WorkingDirectory=/opt/zodiac/backend/backend-fastapi Environment="PATH=/usr/local/python3.12/bin:%PATH" ExecStart=/usr/local/python3.12/bin/python3.12 -m uvicorn app.main:app --port 3000 --host 0.0.0.0 Restart=always RestartSec=5 # 日志 StandardOutput=journal StandardError=journal SyslogIdentifier=zodiac-backend [Install] WantedBy=multi-user.target ``` ```bash # 启动服务 sudo systemctl daemon-reload sudo systemctl start zodiac-backend sudo systemctl enable zodiac-backend # 查看状态 sudo systemctl status zodiac-backend ``` ### 5. 验证后端服务 ```bash # 测试健康检查 curl http://localhost:3000/health # 预期输出 {"status":"healthy"} ``` --- ## 应用服务器部署 (菜鸟测试 1) ### 1. 部署前端 ```bash # 创建部署目录 sudo mkdir -p /var/www/mobile/dist sudo chown -R nginx:nginx /var/www/mobile/dist # 方法 1: 从开发环境复制 # 在开发环境执行: cd /home/admin/.openclaw/workspace/zodiac-collector/zodiac-mobile npm run build # 打包后复制到测试服务器 scp -r dist/* root@47.103.29.111:/var/www/mobile/dist/ # 方法 2: 在测试服务器构建 cd /opt git clone http://47.253.189.47:3000/coolbot/zodiac-collector.git cd zodiac-collector/zodiac-mobile npm install npm run build sudo cp -r dist/* /var/www/mobile/dist/ sudo chown -R nginx:nginx /var/www/mobile/dist/ ``` ### 2. Nginx 配置 ```bash # 创建 Nginx 配置文件 sudo vi /etc/nginx/conf.d/zodiac.conf ``` ```nginx types { application/javascript js; text/css css; } server { listen 3001; server_name _; root /var/www/mobile/dist; index index.html; # 允许上传最大 20MB 的文件 client_max_body_size 20M; # 前端静态文件 location / { try_files $uri $uri/ /index.html; # 缓存配置 location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { expires 1y; add_header Cache-Control "public, immutable"; } } # API 代理到后端服务器 location /api { proxy_pass http://47.103.9.192:3000/api; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 允许大文件上传 client_max_body_size 20M; # 超时配置 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # 日志配置 access_log /var/log/nginx/zodiac-access.log; error_log /var/log/nginx/zodiac-error.log; } ``` ```bash # 测试 Nginx 配置 sudo nginx -t # 启动 Nginx sudo systemctl start nginx sudo systemctl enable nginx # 重载配置 sudo systemctl reload nginx ``` ### 3. Prometheus 监控配置 (可选) ```bash # 创建 Prometheus 目录 sudo mkdir -p /opt/prometheus cd /opt/prometheus # 下载并解压 wget https://github.com/prometheus/prometheus/releases/download/v2.45.0/prometheus-2.45.0.linux-amd64.tar.gz tar xvfz prometheus-*.tar.gz cd prometheus-2.45.0.linux-amd64 # 创建配置文件 cat > prometheus.yml << EOF global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: 'zodiac-backend' static_configs: - targets: ['47.103.9.192:3000'] metrics_path: '/metrics' - job_name: 'nginx' static_configs: - targets: ['localhost:9113'] # nginx exporter EOF # 创建 systemd 服务 sudo vi /etc/systemd/system/prometheus.service ``` ```ini [Unit] Description=Prometheus Monitoring After=network.target [Service] Type=simple User=prometheus WorkingDirectory=/opt/prometheus/prometheus-2.45.0.linux-amd64 ExecStart=/opt/prometheus/prometheus-2.45.0.linux-amd64/prometheus --config.file=prometheus.yml Restart=always [Install] WantedBy=multi-user.target ``` ```bash # 启动 Prometheus sudo systemctl daemon-reload sudo systemctl start prometheus sudo systemctl enable prometheus ``` --- ## 部署验证与测试 ### 1. 基础服务检查 ```bash # 菜鸟测试 1 systemctl status nginx systemctl status prometheus # 如安装 # 菜鸟测试 2 systemctl status zodiac-backend systemctl status postgresql # 端口检查 netstat -tlnp | grep -E "3001|3000|5432|9090" ``` ### 2. 数据库连接测试 ```bash # 在菜鸟测试 2 上 psql -U postgres -d zodiac -c "SELECT version();" # 在菜鸟测试 1 上测试远程连接 psql -h 47.103.9.192 -U postgres -d zodiac -c "SELECT version();" ``` ### 3. 后端 API 测试 ```bash # 健康检查 curl http://47.103.9.192:3000/health # API 文档 curl http://47.103.9.192:3000/docs # 登录测试 curl -X POST http://47.103.9.192:3000/api/auth/login \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin&password=admin123" ``` ### 4. 前端访问测试 ```bash # 访问前端页面 curl http://47.103.29.111:3001/ # 应该返回 HTML 内容 ``` ### 5. 完整功能测试清单 | 功能 | 测试步骤 | 预期结果 | |------|---------|---------| | 登录 | 访问 http://47.103.29.111:3001/，使用 admin/admin123 登录 | ✅ 登录成功，跳转首页 | | 注册 | 点击"注册新账号"，填写信息并提交 | ✅ 注册成功 | | 藏品列表 | 查看藏品列表 | ✅ 显示藏品数据 | | 添加藏品 | 手工录入一个藏品 | ✅ 保存成功，编码自动生成 | | 图片上传 | 上传藏品图片 | ✅ 上传成功，显示图片 | | 筛选功能 | 按状态/珍惜度等筛选 | ✅ 筛选条件显示中文 | | 统计页面 | 查看统计分析 | ✅ 显示 8 个分布统计 | | 用户管理 | 管理员添加/删除用户 | ✅ 功能正常 | --- ## 错误码与故障排查 ### 📋 完整错误码列表 #### 认证错误 (E00010-E00019) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00010** | 未登录或登录已过期 | 401 | 重新登录获取新 Token | | **E00011** | 用户名或密码错误 | 401 | 检查用户名密码是否正确 | | **E00012** | 验证码错误 | 400 | 刷新验证码后重试 | | **E00014** | 无权访问此资源 | 403 | 检查用户权限（需管理员） | | **E00015** | 令牌无效或已过期 | 401 | 清除本地存储，重新登录 | #### 验证错误 (E00020-E00029) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00020** | 请输入用户名和密码 | 400 | 填写完整的登录信息 | | **E00021** | 用户名至少 3 个字符 | 400 | 用户名长度≥3 字符 | | **E00022** | 密码至少 6 个字符 | 400 | 密码长度≥6 字符 | | **E00023** | 用户名已存在 | 400 | 更换其他用户名 | | **E00024** | 邮箱已被注册 | 400 | 更换其他邮箱 | #### 藏品管理错误 (E00030-E00039) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00030** | 藏品名称不能为空 | 400 | 填写藏品名称 | | **E00031** | 藏品名称至少 2 个字符 | 400 | 名称长度≥2 字符 | | **E00032** | 藏品分类不能为空 | 400 | 选择藏品分类 | | **E00033** | 藏品不存在 | 404 | 检查藏品 ID 是否正确 | | **E00034** | 禁止重复：此冠字号已存在 | 400 | 检查冠字号是否重复 | | **E00035** | 成本价格必须>=0 | 400 | 价格不能为负数 | | **E00036** | 目标价格必须>=0 | 400 | 价格不能为负数 | | **E00037** | 发行年份必须是 4 位数字 | 400 | 年份格式：YYYY | #### OCR 识别错误 (E00040-E00049) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00040** | 请选择图片文件 | 400 | 上传正确的图片 | | **E00041** | 图片尺寸太小，无法识别 | 400 | 上传更清晰的图片 | | **E00042** | OCR 识别失败，请重试 | 500 | 重新上传或检查 API Key | #### 用户管理错误 (E00050-E00059) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00050** | 仅管理员可访问 | 403 | 需要管理员权限 | | **E00051** | 用户不存在 | 404 | 检查用户 ID 是否正确 | | **E00052** | 不能删除自己 | 400 | 不能删除当前登录用户 | #### 通用错误 (E00000-E00009) | 错误码 | 说明 | HTTP 状态 | 解决方案 | |--------|------|----------|---------| | **E00000** | 请求失败 | - | 检查请求参数 | | **E00001** | 网络连接失败 | - | 检查网络连接 | | **E00003** | 服务器内部错误 | 500 | 联系管理员查看日志 | --- ### 🔧 常见错误处理流程 #### 1. E00010: 未登录或登录已过期 **现象**: 访问任何需要登录的页面都提示 E00010 **原因**: - Token 已过期（默认 60 分钟） - Token 被篡改或无效 - 本地存储被清除 **解决方案**: ```javascript // 浏览器控制台执行 localStorage.clear() sessionStorage.clear() // 然后刷新页面，重新登录 ``` **预防措施**: - 设置合理的 Token 有效期（建议 24 小时） - 前端实现 Token 自动刷新机制 --- #### 2. E00011: 用户名或密码错误 **现象**: 登录时提示用户名或密码错误 **原因**: - 用户名或密码输入错误 - 大小写问题 - 用户不存在 **解决方案**: 1. 检查用户名密码是否正确 2. 确认大小写（密码区分大小写） 3. 联系管理员确认账号是否存在 --- #### 3. E00033: 藏品不存在 **现象**: 访问藏品详情时提示藏品不存在 **原因**: - 藏品 ID 错误 - 藏品已被删除 - 无权访问此藏品 **解决方案**: 1. 检查藏品 ID 是否正确 2. 确认藏品是否被删除 3. 确认是否有访问权限 --- #### 4. E00042: OCR 识别失败 **现象**: 上传图片识别时失败 **错误日志**: ``` OCR API 调用失败：{"error": {"message": "Invalid API Key", ...}} OCR API 调用失败：{"error": {"message": "you must provide a messages parameter", ...}} ``` **原因**: - 阿里云 API Key 配置错误/失效 - API 请求格式不正确（兼容模式 vs 原生模式） - 图片格式不支持 - 图片质量太差 - API 余额不足 **解决方案**: **1. 检查 API Key 配置** ```bash # 检查后端 .env 配置 cat .env | grep DASHSCOPE_API_KEY # 应该显示： # DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx ``` **2. 验证 API Key 有效性** ```bash # 测试 API Key curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-vl-max", "input": { "messages": [{ "role": "user", "content": [{"type": "text", "text": "你好"}] }] } }' # 成功返回：{"output": {"choices": [...]}} # 失败返回：{"error": {"message": "..."}} ``` **3. 检查 API 请求格式** ```python # ✅ 正确格式（2026 年兼容模式） payload = { "model": "qwen-vl-max", "input": { "messages": [{ "role": "user", "content": [ {"type": "image", "image": "data:image/jpeg;base64,..."}, {"type": "text", "text": "提示词"} ] }] }, "parameters": { "max_tokens": 1000 } } # ❌ 错误格式（旧版） payload = { "model": "qwen-vl-max", "messages": [...] # 缺少 input 包裹 } ``` **4. 获取新的 API Key** ``` 1. 访问：https://dashscope.console.aliyun.com/apiKey 2. 登录阿里云账号 3. 创建/复制 API Key 4. 更新 .env 配置 5. 重启后端服务 ``` **5. 检查 API 余额** ``` 访问：https://dashscope.console.aliyun.com/overview 查看：剩余额度和用量 ``` --- #### 5. E00050: 仅管理员可访问 **现象**: 访问用户管理页面时提示无权访问 **原因**: - 当前用户不是管理员角色 **解决方案**: 1. 联系管理员提升权限 2. 使用管理员账号登录 --- #### 5.5. OCR 识别成功但字段未保存 **现象**: OCR 识别成功，但 11 个字段信息没有正确保存到表单 **原因**: - 后端返回的字段名与前端期望不一致 - 字段映射错误 - 布尔值处理问题 **后端返回字段** (`data.fields`): ```json { "issuer": "中国人民银行", "version": "2024 龙", "denomination": "贰拾圆", "prefix_serial": "J01234567", "packaging": "标十", "grading_company": "ACG", "grading_score": "68", "special_mark": "金山标", "serial_feature": "金山号 2 张", "is_graded": true, "three_star": false } ``` **前端期望字段** (form 状态): ```javascript { issuer: "中国人民银行", version: "2024 龙", denomination: "贰拾圆", prefixSerial: "J01234567", // ⚠️ 驼峰命名 packaging: "标十", gradingCompany: "ACG", // ⚠️ 驼峰命名 gradingScore: "68", // ⚠️ 驼峰命名 specialMark: "金山标", // ⚠️ 驼峰命名 serialFeature: "金山号 2 张", // ⚠️ 驼峰命名 isGraded: true, // ⚠️ 驼峰命名 threeStar: false // ⚠️ 驼峰命名 } ``` **解决方案**: **前端修复** (`Add.jsx` 的 `handleRecognize`): ```javascript if (data.fields) { const recognizedForm = { ...getDefaultForm() } // 下划线 → 驼峰 映射 if (data.fields.issuer) recognizedForm.issuer = data.fields.issuer if (data.fields.version) recognizedForm.version = data.fields.version if (data.fields.denomination) recognizedForm.denomination = data.fields.denomination if (data.fields.prefix_serial) recognizedForm.prefixSerial = data.fields.prefix_serial // ✅ if (data.fields.packaging) recognizedForm.packaging = data.fields.packaging if (data.fields.grading_company) recognizedForm.gradingCompany = data.fields.grading_company // ✅ if (data.fields.grading_score) recognizedForm.gradingScore = data.fields.grading_score // ✅ if (data.fields.special_mark && data.fields.special_mark !== '无') recognizedForm.specialMark = data.fields.special_mark // ✅ if (data.fields.serial_feature && data.fields.serial_feature !== '无') recognizedForm.serialFeature = data.fields.serial_feature // ✅ // 布尔字段 if (data.fields.is_graded !== undefined) recognizedForm.isGraded = data.fields.is_graded if (data.fields.three_star !== undefined) recognizedForm.threeStar = data.fields.three_star } ``` **调试方法**: ```javascript // 在 handleRecognize 中添加 console.log('后端返回:', data.fields) console.log('转换后:', recognizedForm) ``` --- #### 6. 识别失败：Unexpected token '<', " 1MB，需要配置 Nginx ``` **配置 Nginx 图片上传限制**: ```nginx server { listen 3001; # ⚠️ 必须配置：允许上传 20MB client_max_body_size 20M; location /api { proxy_pass http://127.0.0.1:3000/api; # ⚠️ API 上传也要配置 client_max_body_size 20M; } } ``` **重启 Nginx**: ```bash sudo nginx -t && sudo nginx -s reload ``` --- **方案 3: 检查访问的 URL** ```javascript // 正确 URL http://47.103.29.111:3001/ // 错误 URL http://47.103.29.111/ // 默认 80 端口 http://47.103.29.111:8080/ // 错误端口 http://47.103.29.111:3000/ // 后端端口（不能直接访问） ``` --- **方案 4: 检查后端服务** ```bash # SSH 登录测试服务器 ssh root@47.103.9.192 # 检查后端健康状态 curl http://localhost:3000/health # 应该返回：{"status":"healthy"} # 如果返回空或报错，检查后端服务 systemctl status zodiac-backend # 查看后端日志 sudo journalctl -u zodiac-backend -n 50 --no-pager ``` --- ##### 快速诊断脚本 ```bash #!/bin/bash # 保存为 check-api.sh echo "=== 检查后端服务 ===" curl -s http://localhost:3000/health | jq . echo "" echo "=== 检查 Nginx 配置 ===" nginx -t 2>&1 | grep -i 'client_max_body_size' echo "" echo "=== 检查 Nginx 错误日志 ===" sudo tail -20 /var/log/nginx/error.log | grep -i 'large\|body\|client' ``` --- ##### 预防措施 1. **前端添加版本号** ```html ``` 2. **Nginx 配置正确的错误页面** ```nginx error_page 502 /502.html; error_page 413 /413.html; ``` 3. **监控后端服务状态** ```bash # 添加到 crontab */5 * * * * curl -f http://localhost:3000/health || systemctl restart zodiac-backend ``` 4. **前端添加错误处理** ```javascript try { const res = await fetch('/api/...') const data = await res.json() } catch (err) { if (err.message.includes('Unexpected token')) { alert('服务暂时不可用，请清除缓存后重试') } } ``` --- ### 📝 故障排查通用步骤 ``` 1. 查看错误码 → 2. 查看错误信息 → 3. 查看日志 → 4. 定位问题 ``` **后端日志**: ```bash # 查看后端日志 sudo journalctl -u zodiac-backend -f # 查看最近 100 行 sudo journalctl -u zodiac-backend -n 100 ``` **Nginx 日志**: ```bash # 访问日志 sudo tail -f /var/log/nginx/zodiac-access.log # 错误日志 sudo tail -f /var/log/nginx/zodiac-error.log ``` **数据库日志**: ```bash # PostgreSQL 日志 sudo tail -f /var/log/postgresql/postgresql-13-main.log ``` **浏览器控制台**: ``` F12 打开开发者工具 → Console 标签 → 查看 JavaScript 错误 ``` --- ## 常见问题与解决方案 ### 问题 1: Nginx 启动失败 **现象**: `systemctl status nginx` 显示失败 **解决方案**: ```bash # 检查配置 sudo nginx -t # 查看错误日志 sudo tail -50 /var/log/nginx/error.log # 常见原因: # 1. 端口被占用：netstat -tlnp | grep 3001 # 2. 配置文件错误：检查 /etc/nginx/conf.d/zodiac.conf # 3. 权限问题：sudo chown -R nginx:nginx /var/www/mobile/dist ``` ### 问题 2: 后端无法连接数据库 **现象**: 后端日志显示数据库连接失败 **解决方案**: ```bash # 1. 检查 PostgreSQL 是否运行 systemctl status postgresql # 2. 检查 pg_hba.conf 配置 sudo cat /var/lib/pgsql/data/pg_hba.conf | grep -v "^#" # 3. 测试数据库连接 psql -h localhost -U postgres -d zodiac # 4. 检查防火墙 firewall-cmd --list-all | grep 5432 ``` ### 问题 3: 前端页面空白 **现象**: 访问 http://47.103.29.111:3001/ 显示空白 **解决方案**: ```bash # 1. 检查 Nginx 日志 sudo tail -50 /var/log/nginx/zodiac-error.log # 2. 检查前端文件是否存在 ls -la /var/www/mobile/dist/ # 3. 检查浏览器控制台错误 # F12 打开开发者工具，查看 Console 和 Network 标签 # 4. 清除浏览器缓存 # Ctrl+Shift+R 强制刷新 ``` ### 问题 4: 图片上传失败 (413 错误) **现象**: 上传图片时返回 413 Request Entity Too Large **解决方案**: ```bash # 检查 Nginx 配置 sudo grep -i "client_max_body_size" /etc/nginx/conf.d/zodiac.conf # 确保配置了 20M client_max_body_size 20M; # 重载 Nginx sudo nginx -t && sudo nginx -s reload ``` ### 问题 5: 跨域访问失败 **现象**: 前端调用 API 时出现 CORS 错误 **解决方案**: ```bash # 检查后端 CORS 配置 cat /opt/zodiac/backend/backend-fastapi/app/main.py | grep -A 10 "CORS" # 确保配置了允许所有来源 (开发/测试环境) app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` ### 问题 6: Prometheus 无法抓取指标 **现象**: Prometheus 界面显示 target down **解决方案**: ```bash # 1. 检查后端是否暴露 metrics 端点 curl http://47.103.9.192:3000/metrics # 2. 检查 Prometheus 配置 cat /opt/prometheus/prometheus-2.45.0.linux-amd64/prometheus.yml # 3. 重启 Prometheus sudo systemctl restart prometheus ``` --- ## 维护与监控 ### 1. 日志管理 ```bash # 后端日志 sudo journalctl -u zodiac-backend -f # Nginx 日志 sudo tail -f /var/log/nginx/zodiac-access.log sudo tail -f /var/log/nginx/zodiac-error.log # PostgreSQL 日志 sudo tail -f /var/log/postgresql/postgresql-13-main.log # Ubuntu # 或 sudo tail -f /var/lib/pgsql/data/log/postgresql.log # CentOS # Prometheus 日志 sudo journalctl -u prometheus -f ``` ### 2. 备份策略 ```bash # 数据库备份脚本 cat > /opt/backup-zodiac.sh << 'EOF' #!/bin/bash BACKUP_DIR="/opt/backups/zodiac" DATE=$(date +%Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR # 备份数据库 pg_dump -U postgres -h localhost zodiac > $BACKUP_DIR/zodiac_$DATE.sql # 备份上传文件 tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /opt/zodiac/backend/backend-fastapi/uploads/ # 删除 7 天前的备份 find $BACKUP_DIR -name "*.sql" -mtime +7 -delete find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete echo "备份完成：$DATE" EOF chmod +x /opt/backup-zodiac.sh # 添加到 crontab (每天凌晨 2 点备份) crontab -e 0 2 * * * /opt/backup-zodiac.sh >> /var/log/zodiac-backup.log 2>&1 ``` ### 3. 监控告警 ```bash # Prometheus 告警规则示例 cat > /opt/prometheus/prometheus-2.45.0.linux-amd64/rules.yml << EOF groups: - name: zodiac_alerts rules: - alert: BackendDown expr: up{job="zodiac-backend"} == 0 for: 1m labels: severity: critical annotations: summary: "甲辰后端服务宕机" description: "后端服务 {{ \$labels.instance }} 已宕机超过 1 分钟" - alert: DatabaseDown expr: pg_up == 0 for: 1m labels: severity: critical annotations: summary: "PostgreSQL 数据库宕机" description: "数据库 {{ \$labels.instance }} 已宕机超过 1 分钟" EOF ``` ### 4. 性能优化建议 #### Nginx 优化 ```nginx # 启用 gzip 压缩 gzip on; gzip_types text/plain text/css application/json application/javascript; gzip_min_length 1000; # 连接优化 worker_connections 1024; keepalive_timeout 65; ``` #### PostgreSQL 优化 ```conf # postgresql.conf shared_buffers = 2GB # 内存的 25% effective_cache_size = 6GB # 内存的 75% work_mem = 64MB maintenance_work_mem = 512MB ``` #### FastAPI 优化 ```bash # 使用 gunicorn + uvicorn workers pip install gunicorn # 启动命令 gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:3000 ``` --- ## 附录 ### A. 快速部署脚本 ```bash #!/bin/bash # 快速部署脚本 - 菜鸟测试 2 (数据库服务器) set -e echo "=== 甲辰系统快速部署脚本 ===" # 1. 安装依赖 echo "安装依赖..." sudo yum install -y postgresql13-server postgresql13 git python3.12 # 2. 初始化数据库 echo "初始化数据库..." sudo postgresql-setup --initdb sudo systemctl start postgresql sudo systemctl enable postgresql # 3. 创建数据库 echo "创建数据库..." sudo -u postgres psql -c "CREATE DATABASE zodiac;" sudo -u postgres psql -c "CREATE USER postgres WITH PASSWORD 'postgres' SUPERUSER;" sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE zodiac TO postgres;" # 4. 配置远程访问 echo "配置远程访问..." echo "host zodiac postgres 47.103.29.111/32 md5" | sudo tee -a /var/lib/pgsql/data/pg_hba.conf echo "listen_addresses = '*'" | sudo tee -a /var/lib/pgsql/data/postgresql.conf sudo systemctl restart postgresql # 5. 部署后端 echo "部署后端..." sudo mkdir -p /opt/zodiac/backend sudo chown -R $USER:$USER /opt/zodiac/backend cd /opt/zodiac/backend git clone http://47.253.189.47:3000/coolbot/zodiac-collector.git . git checkout v2.7.9 cd backend-fastapi pip3.12 install -r requirements.txt # 6. 创建服务 echo "创建系统服务..." sudo cp zodiac-backend.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl start zodiac-backend sudo systemctl enable zodiac-backend echo "=== 部署完成 ===" echo "访问地址：http://47.103.29.111:3001/" echo "默认账号：admin / admin123" ``` ### B. 联系信息 - **开发团队**: 菜鸟小 D (AI 开发助理) - **技术支持**: 酷博特 - **文档版本**: v1.0 - **最后更新**: 2026-03-15 --- **文档结束**