quality-inspection-platform/docs/deploy_docker.md

Docker / Docker Compose 部署

在 CentOS 7 或其它 Linux 上，用容器自带 Python 3.11，无需在宿主机安装 Python 3.11 / Node。

---

0. 宿主机准备

CentOS 7 安装 Docker

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

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 时）

在本机项目根目录：

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/

在服务器上：

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. 配置环境变量

cp .env.example .env
vi .env   # 修改 AUTH_TOKEN_SECRET、DEFAULT_SUPERADMIN_PASSWORD 等

---

3. 准备数据目录

sudo mkdir -p /docker_data
sudo chown -R "$(id -u)":"$(id -g)" /docker_data

---

4. 在服务器上构建并启动

cd /opt/quality-inspection-platform

docker compose build
docker compose up -d

docker compose ps
docker compose logs -f

---

5. 验证

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）：

{
  "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 内联脚本等

部署前在服务器上准备目录：

sudo mkdir -p /docker_data
# 官方 python:3.11-slim 镜像内进程用户多为 root；若以后改用非 root 用户，再改属主
sudo chown -R "$(id -u)":"$(id -g)" /docker_data

改用其它目录时，在 .env 中设置：

QIP_DATA_HOST_DIR=/your/path

备份数据库（直接在宿主机）：

cp /docker_data/ai_test.db /docker_data/ai_test.db.bak.$(date +%Y%m%d)

---

7. 常用命令

# 停止
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）

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：

{
  "registry-mirrors": []
}

或改成你们内网可访问的镜像地址。然后：

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
• MCP 配置：mcp_install.md