# 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)