wecom-ai-assistant/docs/baota-docker-setup.md

# 宝塔面板 Docker 私有镜像拉取指南

## 概述

本指南介绍如何在宝塔面板中使用 Docker 拉取私有 Registry 的镜像。

## 私有 Registry 信息

- **Registry URL**: `git.quanyu360.cn`
- **用户名**: `admin`
- **密码**: `ye972030`
- **命名空间**: `wecom-ai`
- **镜像名称**:
  - Backend: `git.quanyu360.cn/wecom-ai/wecom-ai-backend:latest`
  - Admin: `git.quanyu360.cn/wecom-ai/wecom-ai-admin:latest`

## 方法一：在宝塔面板中配置 Docker 登录（推荐）

### 步骤 1：登录 Docker Registry

1. **打开宝塔面板终端**：
   - 登录宝塔面板
   - 点击左侧菜单 **"终端"** 或 **"SSH终端"**

2. **执行登录命令**：
   ```bash
   docker login git.quanyu360.cn -u admin -p ye972030
   ```

3. **验证登录**：
   ```bash
   # 查看登录信息（凭据存储在 ~/.docker/config.json）
   cat ~/.docker/config.json | grep git.quanyu360.cn
   ```

### 步骤 2：拉取镜像

登录成功后，可以直接拉取镜像：

```bash
# 拉取 Backend 镜像
docker pull git.quanyu360.cn/wecom-ai/wecom-ai-backend:latest

# 拉取 Admin 镜像
docker pull git.quanyu360.cn/wecom-ai/wecom-ai-admin:latest

# 查看拉取的镜像
docker images | grep git.quanyu360.cn
```

### 步骤 3：使用 docker-compose 部署

在宝塔面板中：

1. **创建项目目录**：
   ```bash
   mkdir -p /www/wwwroot/wecom-ai-assistant
   cd /www/wwwroot/wecom-ai-assistant
   ```

2. **上传项目文件**：
   - 使用宝塔文件管理器上传项目文件
   - 或使用 Git 克隆：
     ```bash
     git clone https://admin:ye972030@git.quanyu360.cn/admin/wecom-ai-assistant.git .
     ```

3. **配置环境变量**：
   ```bash
   cp .env.prod.example .env.prod
   # 编辑 .env.prod，填写生产环境变量
   nano .env.prod
   ```

4. **启动服务**：
   ```bash
   docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
   ```

## 方法二：在 docker-compose.yml 中配置认证

### 创建认证文件

在服务器上创建 Docker 认证配置：

```bash
# 创建认证目录
mkdir -p ~/.docker

# 登录（会自动创建认证文件）
docker login git.quanyu360.cn -u admin -p ye972030
```

### 更新 docker-compose.prod.yml

确保 `docker-compose.prod.yml` 中的镜像地址正确：

```yaml
services:
  backend:
    image: git.quanyu360.cn/wecom-ai/wecom-ai-backend:${IMAGE_TAG:-latest}
    # ... 其他配置
```

### 使用环境变量

在 `.env.prod` 中配置：

```bash
REGISTRY_URL=git.quanyu360.cn
REGISTRY_NAMESPACE=wecom-ai
IMAGE_TAG=latest
```

## 方法三：使用宝塔 Docker 管理器

### 步骤 1：安装 Docker 管理器

1. 在宝塔面板中，点击 **"软件商店"**
2. 搜索 **"Docker管理器"** 或 **"Docker"**
3. 点击安装

### 步骤 2：配置 Registry

1. 打开 **Docker管理器**
2. 找到 **"镜像管理"** 或 **"Registry"** 选项
3. 添加私有 Registry：
   - Registry URL: `git.quanyu360.cn`
   - 用户名: `admin`
   - 密码: `ye972030`

### 步骤 3：拉取镜像

1. 在 Docker 管理器中，点击 **"镜像"** 或 **"Images"**
2. 点击 **"拉取镜像"** 或 **"Pull"**
3. 输入镜像名称：
   - `git.quanyu360.cn/wecom-ai/wecom-ai-backend:latest`
   - `git.quanyu360.cn/wecom-ai/wecom-ai-admin:latest`
4. 点击拉取

## 方法四：使用脚本自动化

### 创建拉取脚本

在服务器上创建脚本 `pull-images.sh`：

```bash
#!/bin/bash

# Docker Registry 配置
REGISTRY_URL="git.quanyu360.cn"
REGISTRY_USER="admin"
REGISTRY_PASS="ye972030"
NAMESPACE="wecom-ai"

# 登录 Registry
echo "登录 Docker Registry..."
echo "$REGISTRY_PASS" | docker login $REGISTRY_URL -u $REGISTRY_USER --password-stdin

# 拉取镜像
echo "拉取 Backend 镜像..."
docker pull ${REGISTRY_URL}/${NAMESPACE}/wecom-ai-backend:latest

echo "拉取 Admin 镜像..."
docker pull ${REGISTRY_URL}/${NAMESPACE}/wecom-ai-admin:latest

# 查看镜像
echo "已拉取的镜像:"
docker images | grep $REGISTRY_URL

echo "完成！"
```

### 使用脚本

```bash
# 赋予执行权限
chmod +x pull-images.sh

# 执行脚本
./pull-images.sh
```

## 在宝塔面板中使用 docker-compose

### 步骤 1：安装 docker-compose

如果宝塔面板没有安装 docker-compose：

```bash
# 方法 1：使用 pip 安装
pip3 install docker-compose

# 方法 2：下载二进制文件
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version
```

### 步骤 2：配置项目

1. **创建项目目录**（在宝塔文件管理器中）：
   - 路径：`/www/wwwroot/wecom-ai-assistant`

2. **上传文件**：
   - 上传 `docker-compose.prod.yml`
   - 上传 `.env.prod`（或创建）
   - 上传 `deploy/docker/nginx.conf`

3. **配置环境变量**（`.env.prod`）：
   ```bash
   # Registry 配置
   REGISTRY_URL=git.quanyu360.cn
   REGISTRY_NAMESPACE=wecom-ai
   IMAGE_TAG=latest
   
   # WeCom 配置
   WECOM_CORP_ID=你的企业ID
   WECOM_AGENT_ID=你的应用AgentId
   WECOM_TOKEN=你的Token
   WECOM_ENCODING_AES_KEY=你的43位密钥
   
   # 其他配置...
   ```

### 步骤 3：启动服务

在宝塔终端中执行：

```bash
cd /www/wwwroot/wecom-ai-assistant

# 登录 Docker Registry
docker login git.quanyu360.cn -u admin -p ye972030

# 启动服务
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f
```

## 更新镜像

### 拉取最新镜像

```bash
# 拉取最新镜像
docker pull git.quanyu360.cn/wecom-ai/wecom-ai-backend:latest
docker pull git.quanyu360.cn/wecom-ai/wecom-ai-admin:latest

# 重启服务（使用新镜像）
cd /www/wwwroot/wecom-ai-assistant
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d --force-recreate
```

### 使用特定标签

```bash
# 拉取指定标签的镜像
docker pull git.quanyu360.cn/wecom-ai/wecom-ai-backend:v1.0.0

# 更新 .env.prod 中的 IMAGE_TAG
# IMAGE_TAG=v1.0.0

# 重启服务
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
```

## 故障排查

### 问题 1：拉取镜像时提示认证失败

**解决方案**：
```bash
# 重新登录
docker login git.quanyu360.cn -u admin -p ye972030

# 检查认证文件
cat ~/.docker/config.json
```

### 问题 2：docker-compose 无法拉取私有镜像

**解决方案**：
1. 确保已登录：`docker login git.quanyu360.cn -u admin -p ye972030`
2. 检查镜像名称是否正确
3. 检查网络连接

### 问题 3：宝塔面板中无法使用 docker-compose

**解决方案**：
1. 使用 SSH 终端而不是宝塔终端
2. 或安装 docker-compose 插件
3. 或使用 `docker compose`（新版本 Docker 内置）

## 安全建议

1. **保护凭据**：
   - `.env.prod` 文件不要提交到 Git
   - Docker 认证文件 `~/.docker/config.json` 权限设置为 600

2. **使用环境变量**：
   - 密码等敏感信息存储在环境变量中
   - 不要硬编码在配置文件中

3. **定期更新**：
   - 定期更新镜像
   - 定期轮换密码

## 相关文档

- [私有仓库配置](./private-registry-setup.md)
- [生产部署指南](./deploy.md)
- [Docker Compose 配置](../docker-compose.prod.yml)