qihongkun
f5143aee09
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置 - 新增 MCP 原生集成模块 (mcp_native.py) - 移除旧的 mcp_bridge.py，更新依赖和文档 - 添加部署文档 (Docker 和服务器部署指南) Co-authored-by: Cursor <cursoragent@cursor.com>
243 lines
5.2 KiB
Markdown
243 lines
5.2 KiB
Markdown
# Docker / Docker Compose 部署
|
||
|
||
在 **CentOS 7** 或其它 Linux 上，用容器自带 Python 3.11，**无需**在宿主机安装 Python 3.11 / Node。
|
||
|
||
---
|
||
|
||
## 0. 宿主机准备
|
||
|
||
### CentOS 7 安装 Docker
|
||
|
||
```bash
|
||
sudo yum install -y yum-utils
|
||
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
|
||
sudo yum install -y docker-ce docker-ce-cli containerd.io
|
||
|
||
sudo systemctl enable docker
|
||
sudo systemctl start docker
|
||
|
||
# Compose 插件（v2）
|
||
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" \
|
||
-o /usr/local/bin/docker-compose
|
||
sudo chmod +x /usr/local/bin/docker-compose
|
||
docker compose version
|
||
```
|
||
|
||
内网无法访问外网时，请改用内网镜像源或离线 rpm 包。
|
||
|
||
---
|
||
|
||
## 1. 上传源码到服务器
|
||
|
||
**方式 A：Git**
|
||
|
||
```bash
|
||
sudo mkdir -p /opt/quality-inspection-platform
|
||
sudo chown -R "$USER":"$USER" /opt/quality-inspection-platform
|
||
cd /opt/quality-inspection-platform
|
||
git clone <内网仓库地址> .
|
||
```
|
||
|
||
**方式 B：本机打包上传（无 Git 时）**
|
||
|
||
在本机项目根目录：
|
||
|
||
```bash
|
||
tar czf qip-src.tar.gz \
|
||
--exclude='.venv' --exclude='node_modules' --exclude='frontend-admin/dist' \
|
||
--exclude='ai_test.db' --exclude='.git' \
|
||
.
|
||
scp qip-src.tar.gz user@<服务器>:/tmp/
|
||
```
|
||
|
||
在服务器上：
|
||
|
||
```bash
|
||
sudo mkdir -p /opt/quality-inspection-platform
|
||
sudo tar xzf /tmp/qip-src.tar.gz -C /opt/quality-inspection-platform
|
||
sudo chown -R "$USER":"$USER" /opt/quality-inspection-platform
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
vi .env # 修改 AUTH_TOKEN_SECRET、DEFAULT_SUPERADMIN_PASSWORD 等
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 准备数据目录
|
||
|
||
```bash
|
||
sudo mkdir -p /docker_data
|
||
sudo chown -R "$(id -u)":"$(id -g)" /docker_data
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 在服务器上构建并启动
|
||
|
||
```bash
|
||
cd /opt/quality-inspection-platform
|
||
|
||
docker compose build
|
||
docker compose up -d
|
||
|
||
docker compose ps
|
||
docker compose logs -f
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 验证
|
||
|
||
```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_*`。
|
||
|
||
MCP（Cursor）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quality-inspection-platform": {
|
||
"url": "http://<服务器IP>:8000/mcp",
|
||
"headers": { "Authorization": "Bearer sto-你的密钥" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 数据持久化（宿主机 `/docker_data`）
|
||
|
||
默认把宿主机的 **`/docker_data`** 挂载到容器 **`/data`**：
|
||
|
||
| 宿主机路径 | 容器路径 | 内容 |
|
||
|------------|----------|------|
|
||
| `/docker_data/ai_test.db` | `/data/ai_test.db` | SQLite 数据库 |
|
||
| `/docker_data/ssh-scripts/` | `/data/ssh-scripts/` | SSH 内联脚本等 |
|
||
|
||
部署前在服务器上准备目录：
|
||
|
||
```bash
|
||
sudo mkdir -p /docker_data
|
||
# 官方 python:3.11-slim 镜像内进程用户多为 root；若以后改用非 root 用户，再改属主
|
||
sudo chown -R "$(id -u)":"$(id -g)" /docker_data
|
||
```
|
||
|
||
改用其它目录时，在 `.env` 中设置：
|
||
|
||
```bash
|
||
QIP_DATA_HOST_DIR=/your/path
|
||
```
|
||
|
||
备份数据库（直接在宿主机）：
|
||
|
||
```bash
|
||
cp /docker_data/ai_test.db /docker_data/ai_test.db.bak.$(date +%Y%m%d)
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 常用命令
|
||
|
||
```bash
|
||
# 停止
|
||
docker compose down
|
||
|
||
# 重启
|
||
docker compose restart
|
||
|
||
# 升级（拉代码后）
|
||
git pull
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
|
||
# 进入容器
|
||
docker compose exec quality-inspection-platform sh
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 防火墙（CentOS 7）
|
||
|
||
```bash
|
||
sudo firewall-cmd --permanent --add-port=8000/tcp
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 架构说明
|
||
|
||
```
|
||
Dockerfile（多阶段）
|
||
├─ node:20 → npm run build → frontend-admin/dist
|
||
└─ python:3.11 → pip install + uvicorn
|
||
卷 /data → SQLite + SSH 脚本目录
|
||
```
|
||
|
||
- 镜像内已包含前端静态资源，**宿主机不需要 Node**。
|
||
- 镜像内已包含 Python 与 `mcp` 依赖，**宿主机不需要 Python 3.11**。
|
||
|
||
---
|
||
|
||
## 10. 排障
|
||
|
||
### 10.1 `lookup docker.mirrors.ustc.edu.cn: no such host`
|
||
|
||
说明 Docker 配置了**已失效或内网不可达的镜像加速**，且 DNS 解析失败。
|
||
|
||
**处理：** 编辑 `/etc/docker/daemon.json`（没有则新建），去掉或更换 `registry-mirrors`：
|
||
|
||
```json
|
||
{
|
||
"registry-mirrors": []
|
||
}
|
||
```
|
||
|
||
或改成你们内网可访问的镜像地址。然后：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl restart docker
|
||
docker compose build
|
||
```
|
||
|
||
本仓库 `Dockerfile` 已去掉 `# syntax=docker/dockerfile:1`，避免额外拉取 `docker/dockerfile:1`（在劣质网络下常失败）。
|
||
|
||
### 10.2 完全无法访问 Docker Hub
|
||
|
||
需任选其一：
|
||
|
||
- 配置**内网 Harbor / registry 代理**，在能联网的机器 `docker pull node:20-bookworm-slim python:3.11-slim-bookworm` 后 `docker save`，传到服务器 `docker load`
|
||
- 让运维开放对 `registry-1.docker.io` 或可靠镜像站的访问
|
||
|
||
### 10.3 其它
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| `git was not found`（WARN） | 可忽略；或 `yum install -y git` |
|
||
| 前端 503 | `docker compose build --no-cache` |
|
||
| MCP 连不上 | `.env` 中 `QIP_MCP_DISABLE_DNS_PROTECTION=true` |
|
||
| `/docker_data` 无写权限 | `chown` 见 §3 |
|
||
|
||
---
|
||
|
||
## 11. 相关文档
|
||
|
||
- 裸机部署（不用 Docker）：[deploy_server.md](./deploy_server.md)
|
||
- MCP 配置：[mcp_install.md](./mcp_install.md)
|