# 服务器部署完整步骤（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
```