quality-inspection-platform/docs/deploy_server.md

服务器部署完整步骤（Linux）

本文假设在 一台内网 Linux 服务器 上从零部署，所有命令均在服务器上执行（通过 SSH 登录）。

• 部署目录示例：/opt/quality-inspection-platform
• 运行用户示例：qip（可改成你的业务用户）
• 监听端口：8000（也可用 Nginx 反代 80/443）

CentOS 7 用户：

• 推荐：用 Docker，无需在宿主机装 Python 3.11 → deploy_docker.md
• 裸机部署：系统自带 Python 3.6 不够用 → §1B CentOS 7，再从 §2 继续

---

0. 部署前确认

项目	要求
系统	CentOS 7（见 §1B）或 Ubuntu 20.04+ / Debian 11+（见 §1A）
Python	3.10+（必须，用于 mcp / FastAPI）
Node	18+（仅构建 frontend-admin 时需要）
权限	能 sudo 安装软件、创建用户
网络	能访问内网 Git；npm / pip 可用（或本机构建 dist 后上传）
磁盘	预留 ≥2GB

交付能力（一个 uvicorn 进程）：

• Web 管理端：http://<服务器>:8000/
• API：/api/*
• MCP（Cursor/Codex）：http://<服务器>:8000/mcp
• 数据文件：项目根目录 ai_test.db（SQLite，需备份）

---

1A. 安装系统依赖（Ubuntu / Debian）

sudo apt update
sudo apt install -y git curl ca-certificates \
  python3 python3-venv python3-pip \
  nodejs npm

检查版本：

python3 --version    # 须 >= 3.10
node --version       # 建议 >= 18

若 python3 低于 3.10，请安装更新的 Python 后再继续。
若 nodejs 过旧，改用 NodeSource 安装 18+。

---

1B. 安装系统依赖（CentOS 7）

CentOS 7 默认 python3 为 3.6，无法直接运行本项目。推荐用 IUS 的 Python 3.11 + NodeSource 18。

1B.1 基础工具与编译依赖

sudo yum install -y epel-release
sudo yum install -y git curl ca-certificates gcc make \
  openssl-devel bzip2-devel libffi-devel zlib-devel \
  readline-devel sqlite-devel

1B.2 安装 Python 3.11（IUS）

# 若服务器不能访问外网，请改用内网 yum 源或在本机构好 wheel 再上传
sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
sudo yum install -y python311 python311-pip python311-devel

python3.11 --version    # 应显示 3.11.x

后续所有 python3 / pip 命令在 CentOS 7 上请写成 python3.11 / python3.11 -m pip。

1B.3 安装 Node.js 18（构建前端）

curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

node --version    # 应 >= v18
npm --version

无法访问 NodeSource 时：在开发机 npm run build 后，只把 frontend-admin/dist/ 上传到服务器，可跳过 Node 安装（见 §5 说明）。

1B.4（可选）用 SCL Python 3.8 的说明

部分环境只有 rh-python38（3.8），可能装不上新版 mcp 包。不推荐 CentOS 7 用 3.8 跑本仓库；请优先 3.11。

---

2. 创建运行用户与目录

sudo useradd -r -m -d /opt/qip -s /bin/bash qip 2>/dev/null || true
sudo mkdir -p /opt/quality-inspection-platform
sudo chown -R qip:qip /opt/quality-inspection-platform

后续命令用 qip 执行（或你自己的用户）：

sudo -iu qip
cd /opt/quality-inspection-platform

---

3. 获取代码

方式 A：Git（推荐）

cd /opt/quality-inspection-platform
git clone <你的内网仓库地址> .
# 或指定分支：git clone -b main <url> .

方式 B：上传压缩包

在本机打包后 scp 到服务器，再解压：

cd /opt/quality-inspection-platform
tar xzf quality-inspection-platform.tar.gz --strip-components=1

---

4. 安装 Python 依赖

cd /opt/quality-inspection-platform

# Ubuntu / Debian：
python3 -m venv .venv

# CentOS 7（IUS）：
# python3.11 -m venv .venv

source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

# 验证关键包
python -c "import fastapi, mcp, uvicorn; print('python deps ok')"

CentOS 7 若 pip install 编译失败，确认已执行 §1B.1 的 gcc 与 *-devel 包；或在内网配置 pip 镜像源。

---

5. 构建前端（生产必做）

cd /opt/quality-inspection-platform/frontend-admin

npm install
npm run build

cd ..
ls -la frontend-admin/dist/index.html

必须存在 frontend-admin/dist/index.html，否则浏览器访问 / 会提示前端未构建。

CentOS 7 未装 Node 时：在开发机构建后只上传 dist：

cd frontend-admin && npm install && npm run build
scp -r dist qip@<服务器>:/opt/quality-inspection-platform/frontend-admin/

可选：构建完成后删除 node_modules 节省空间（以后升级需重新 npm install）：

rm -rf /opt/quality-inspection-platform/frontend-admin/node_modules

---

6. 配置环境变量

cd /opt/quality-inspection-platform
mkdir -p data/ssh-scripts

cat > /opt/quality-inspection-platform/.env <<'EOF'
# 生产务必修改下面三项
AUTH_TOKEN_SECRET=请替换为随机长字符串
DEFAULT_SUPERADMIN_USERNAME=admin
DEFAULT_SUPERADMIN_PASSWORD=请替换为强密码

# MCP：强制所有工具带 API Key
MCP_REQUIRE_API_KEY=true

# 同事从其它机器用 Cursor 连 MCP 时，若连不上可开启：
QIP_MCP_DISABLE_DNS_PROTECTION=true
# 或精确白名单（二选一）：
# QIP_MCP_ALLOWED_HOSTS=10.0.0.5:8000,qip.internal:8000
# QIP_MCP_ALLOWED_ORIGINS=http://10.0.0.5:8000

# 可选：Loki 日志探索
# GENERAL_LOKI_EXPLORE_URL=https://grafana.example/explore
EOF

chmod 600 .env

.env 已在 .gitignore 中，不会进 Git。
uvicorn 默认不会自动读 .env；下面 systemd 示例用 EnvironmentFile 加载。

---

7. 首次试跑（前台）

cd /opt/quality-inspection-platform
source .venv/bin/activate

set -a
source .env
set +a

uvicorn app.main:app --host 0.0.0.0 --port 8000

另开一个 SSH 窗口自检：

curl -s http://127.0.0.1:8000/health
# 期望：{"ok":true}

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/
# 期望：200

浏览器访问：http://<服务器IP>:8000/
使用 .env 里的 DEFAULT_SUPERADMIN_USERNAME / DEFAULT_SUPERADMIN_PASSWORD 登录。

确认无误后，在前台试跑窗口 Ctrl+C 停止，进入第 8 步配置 systemd。

---

8. 配置 systemd 常驻

sudo tee /etc/systemd/system/quality-inspection-platform.service <<'EOF'
[Unit]
Description=Quality Inspection Platform
After=network.target

[Service]
Type=simple
User=qip
Group=qip
WorkingDirectory=/opt/quality-inspection-platform
EnvironmentFile=/opt/quality-inspection-platform/.env
Environment=PATH=/opt/quality-inspection-platform/.venv/bin:/usr/bin:/bin
ExecStart=/opt/quality-inspection-platform/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable quality-inspection-platform
sudo systemctl start quality-inspection-platform
sudo systemctl status quality-inspection-platform

查看日志：

journalctl -u quality-inspection-platform -f

---

9. 防火墙（按需）

CentOS 7（firewalld） — 仅内网访问 8000：

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port protocol="tcp" port="8000" accept'
sudo firewall-cmd --reload

若用 Nginx 对外 80：

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

Ubuntu（ufw）：

sudo ufw allow from 10.0.0.0/8 to any port 8000 proto tcp
sudo ufw reload

若前面有 Nginx 对外 80/443，则只开放 80/443，不要把 8000 暴露到公网。

---

10. Nginx 反向代理（可选）

适用于希望用域名访问、或只暴露 80/443 的场景。

# Ubuntu / Debian
sudo apt install -y nginx

# CentOS 7
sudo yum install -y nginx
sudo systemctl enable nginx

sudo tee /etc/nginx/sites-available/quality-inspection-platform <<'EOF'
server {
    listen 80;
    server_name qip.internal;   # 改成你的域名或 IP

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        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;
        # MCP Streamable HTTP 可能需要较长连接
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/quality-inspection-platform /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

此时访问地址变为：http://qip.internal/
MCP URL：http://qip.internal/mcp

可将 systemd 里 uvicorn 改为只监听本机：

ExecStart=.../uvicorn app.main:app --host 127.0.0.1 --port 8000

---

11. 同事配置 MCP（不在服务器装 Python）

每人本机 Cursor ~/.cursor/mcp.json：

{
  "mcpServers": {
    "quality-inspection-platform": {
      "url": "http://qip.internal/mcp",
      "headers": {
        "Authorization": "Bearer sto-个人API密钥"
      }
    }
  }
}

• sto- Key：登录 Web → 个人中心创建
• 详细说明：mcp_install.md

---

12. 数据备份

数据库与上传的 SSH 脚本目录：

# 示例：每日备份 cron
0 2 * * * qip cp /opt/quality-inspection-platform/ai_test.db /opt/qip/backup/ai_test.db.$(date +\%Y\%m\%d)

升级代码时不要覆盖 已有 ai_test.db。

---

13. 版本升级流程

sudo systemctl stop quality-inspection-platform

sudo -iu qip
cd /opt/quality-inspection-platform

# 备份
cp -a ai_test.db ai_test.db.bak.$(date +%Y%m%d)

# 拉代码
git pull

source .venv/bin/activate
pip install -r requirements.txt

cd frontend-admin
npm install
npm run build
cd ..

exit
sudo systemctl start quality-inspection-platform
curl -s http://127.0.0.1:8000/health

---

14. 验收清单

#	检查	命令/操作
1	服务运行	systemctl is-active quality-inspection-platform
2	健康检查	curl -s http://127.0.0.1:8000/health
3	Web 首页	浏览器打开 /，能登录
4	API 文档	http://<主机>:8000/docs
5	MCP 工具列表	curl -s http://127.0.0.1:8000/mcp/tools -H "Authorization: Bearer sto-xxx"
6	改密	登录后修改超管密码；API Key 仅个人保管
7	防火墙	仅内网可达

---

15. 常见问题

现象	处理
访问 / 提示 frontend dist not found	重新执行第 5 步 npm run build，或上传 frontend-admin/dist
ModuleNotFoundError: mcp	第 4 步 pip install -r requirements.txt；CentOS 7 须用 3.11 的 venv
CentOS 7 python3 是 3.6	不要用系统 python3，改用 python3.11 建 venv
pip 编译卡住 / 失败	yum install §1B.1 开发包；配置内网 pip 镜像
IUS / NodeSource 无法访问	内网 yum 镜像；或本机构建 dist + 离线 wheel 装 Python 包
MCP 在 Cursor 里连不上	.env 设 QIP_MCP_DISABLE_DNS_PROTECTION=true 或配置 QIP_MCP_ALLOWED_HOSTS
401 / 无 Key	Web 个人中心创建 sto- Key；或设 MCP_REQUIRE_API_KEY 后请求头带 Bearer
端口被占用	ss -lntp | grep 8000 查占用进程
权限错误	确认 ai_test.db、data/ 目录属主为 qip
SELinux 拦截（CentOS）	临时：sudo setenforce 0 排查；长期：setsebool -P httpd_can_network_connect 1 或按策略放行

---

16. 相关文档

文档	内容
mcp_install.md	MCP / Cursor / 内网排障
mcp_tools_for_ai.md	AI 工具能力与 Recipe
mcp_quickstart.md	curl / HTTP 网关示例

---

快速命令抄录（已装好环境后）

cd /opt/quality-inspection-platform && source .venv/bin/activate
git pull && pip install -r requirements.txt
cd frontend-admin && npm install && npm run build && cd ..
sudo systemctl restart quality-inspection-platform