qihongkun
f5143aee09
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置 - 新增 MCP 原生集成模块 (mcp_native.py) - 移除旧的 mcp_bridge.py，更新依赖和文档 - 添加部署文档 (Docker 和服务器部署指南) Co-authored-by: Cursor <cursoragent@cursor.com>
482 lines
12 KiB
Markdown
482 lines
12 KiB
Markdown
# 服务器部署完整步骤（Linux）
|
||
|
||
本文假设在 **一台内网 Linux 服务器** 上从零部署，所有命令均在服务器上执行（通过 SSH 登录）。
|
||
|
||
- 部署目录示例：`/opt/quality-inspection-platform`
|
||
- 运行用户示例：`qip`（可改成你的业务用户）
|
||
- 监听端口：`8000`（也可用 Nginx 反代 80/443）
|
||
|
||
**CentOS 7 用户**：
|
||
|
||
- **推荐**：用 Docker，无需在宿主机装 Python 3.11 → **[deploy_docker.md](./deploy_docker.md)**
|
||
- 裸机部署：系统自带 Python 3.6 不够用 → **[§1B CentOS 7](#1b-安装系统依赖-centos-7)**，再从 [§2](#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）
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y git curl ca-certificates \
|
||
python3 python3-venv python3-pip \
|
||
nodejs npm
|
||
```
|
||
|
||
检查版本：
|
||
|
||
```bash
|
||
python3 --version # 须 >= 3.10
|
||
node --version # 建议 >= 18
|
||
```
|
||
|
||
若 `python3` 低于 3.10，请安装更新的 Python 后再继续。
|
||
若 `nodejs` 过旧，改用 [NodeSource](https://github.com/nodesource/distributions) 安装 18+。
|
||
|
||
---
|
||
|
||
## 1B. 安装系统依赖（CentOS 7）
|
||
|
||
CentOS 7 默认 `python3` 为 3.6，**无法直接运行本项目**。推荐用 **IUS 的 Python 3.11** + **NodeSource 18**。
|
||
|
||
### 1B.1 基础工具与编译依赖
|
||
|
||
```bash
|
||
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）
|
||
|
||
```bash
|
||
# 若服务器不能访问外网，请改用内网 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（构建前端）
|
||
|
||
```bash
|
||
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. 创建运行用户与目录
|
||
|
||
```bash
|
||
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` 执行（或你自己的用户）：
|
||
|
||
```bash
|
||
sudo -iu qip
|
||
cd /opt/quality-inspection-platform
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 获取代码
|
||
|
||
**方式 A：Git（推荐）**
|
||
|
||
```bash
|
||
cd /opt/quality-inspection-platform
|
||
git clone <你的内网仓库地址> .
|
||
# 或指定分支：git clone -b main <url> .
|
||
```
|
||
|
||
**方式 B：上传压缩包**
|
||
|
||
在本机打包后 `scp` 到服务器，再解压：
|
||
|
||
```bash
|
||
cd /opt/quality-inspection-platform
|
||
tar xzf quality-inspection-platform.tar.gz --strip-components=1
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 安装 Python 依赖
|
||
|
||
```bash
|
||
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. 构建前端（生产必做）
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
cd frontend-admin && npm install && npm run build
|
||
scp -r dist qip@<服务器>:/opt/quality-inspection-platform/frontend-admin/
|
||
```
|
||
|
||
**可选**：构建完成后删除 `node_modules` 节省空间（以后升级需重新 `npm install`）：
|
||
|
||
```bash
|
||
rm -rf /opt/quality-inspection-platform/frontend-admin/node_modules
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 配置环境变量
|
||
|
||
```bash
|
||
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. 首次试跑（前台）
|
||
|
||
```bash
|
||
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 窗口**自检：
|
||
|
||
```bash
|
||
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 常驻
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
journalctl -u quality-inspection-platform -f
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 防火墙（按需）
|
||
|
||
**CentOS 7（firewalld）** — 仅内网访问 8000：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
sudo firewall-cmd --permanent --add-service=http
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
**Ubuntu（ufw）**：
|
||
|
||
```bash
|
||
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 的场景。
|
||
|
||
```bash
|
||
# Ubuntu / Debian
|
||
sudo apt install -y nginx
|
||
|
||
# CentOS 7
|
||
sudo yum install -y nginx
|
||
sudo systemctl enable nginx
|
||
```
|
||
|
||
```bash
|
||
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 改为只监听本机：
|
||
|
||
```ini
|
||
ExecStart=.../uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 同事配置 MCP（不在服务器装 Python）
|
||
|
||
每人本机 Cursor `~/.cursor/mcp.json`：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quality-inspection-platform": {
|
||
"url": "http://qip.internal/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer sto-个人API密钥"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- `sto-` Key：登录 Web → 个人中心创建
|
||
- 详细说明：[mcp_install.md](./mcp_install.md)
|
||
|
||
---
|
||
|
||
## 12. 数据备份
|
||
|
||
数据库与上传的 SSH 脚本目录：
|
||
|
||
```bash
|
||
# 示例：每日备份 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. 版本升级流程
|
||
|
||
```bash
|
||
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_install.md) | MCP / Cursor / 内网排障 |
|
||
| [mcp_tools_for_ai.md](./mcp_tools_for_ai.md) | AI 工具能力与 Recipe |
|
||
| [mcp_quickstart.md](./mcp_quickstart.md) | curl / HTTP 网关示例 |
|
||
|
||
---
|
||
|
||
## 快速命令抄录（已装好环境后）
|
||
|
||
```bash
|
||
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
|
||
```
|