flnxi-Wu/docs/archive/私有镜像仓库部署指南.md

# 私有镜像仓库部署指南

## 📋 概述

本系统支持**私有镜像仓库部署**，确保：
- ✅ 其他公司使用系统时**看不到源码**
- ✅ 直接从构建好的镜像服务器下载镜像
- ✅ 所有依赖资源从国内镜像源下载
- ✅ 支持一键从标准版升级到Pro版

---

## 🏗️ 架构设计

### 镜像仓库结构

```
your-registry.com/
├── flnxi-material:standard-latest  # 标准版镜像
└── flnxi-material:pro-latest      # Pro版镜像
```

### 部署流程

```
1. 开发环境构建镜像
   ↓
2. 推送到私有镜像仓库
   ↓
3. 客户服务器配置镜像仓库地址
   ↓
4. 客户直接拉取镜像部署（无需源码）
```

---

## 🔧 配置步骤

### 0. 快速部署（推荐）

**在 git.1080p.hk 服务器上执行**：
```bash
# 上传部署脚本
scp scripts/server/setup-registry.sh root@git.1080p.hk:/root/

# SSH登录服务器
ssh root@git.1080p.hk

# 执行部署（带认证）
chmod +x /root/setup-registry.sh
REGISTRY_USER=registry-user REGISTRY_PASSWORD=your-secure-password \
  /root/setup-registry.sh

# 或执行部署（无认证，仅内网使用）
/root/setup-registry.sh
```

### 1. 设置私有镜像仓库

#### 1.1 使用Docker Registry（推荐）

**方式1：使用部署脚本（推荐）**
```bash
# 在 git.1080p.hk 服务器上执行
bash scripts/server/setup-registry.sh
```

**方式2：手动部署**
```bash
# 在 git.1080p.hk 服务器上执行
# 拉取Registry镜像
docker pull registry:2

# 运行Registry（HTTP版本，内网使用）
docker run -d \
  --name docker-registry \
  -p 5000:5000 \
  -v /var/lib/docker-registry:/var/lib/registry \
  --restart=always \
  registry:2
```

**方式3：使用Docker Compose（推荐用于生产环境）**
```bash
# 上传 docker-compose-registry.yml 到服务器
scp docker-compose-registry.yml root@git.1080p.hk:/root/

# 启动
ssh root@git.1080p.hk
cd /root
docker compose -f docker-compose-registry.yml up -d
```

#### 1.2 配置HTTPS（生产环境必须）

```bash
# 生成证书
mkdir -p /etc/docker/registry
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout /etc/docker/registry/domain.key \
  -out /etc/docker/registry/domain.crt \
  -days 365 \
  -subj "/CN=your-registry.com"

# 使用HTTPS运行
docker run -d \
  --name docker-registry \
  -p 5000:5000 \
  -v /etc/docker/registry:/certs \
  -v /var/lib/registry:/var/lib/registry \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_PRIVATE_KEY=/certs/domain.key \
  --restart=always \
  registry:2
```

### 2. 构建和推送镜像

#### 2.1 构建标准版镜像

```bash
# 构建镜像
docker build -t your-registry.com:5000/flnxi-material:standard-latest .

# 标记镜像
docker tag your-registry.com:5000/flnxi-material:standard-latest \
  your-registry.com:5000/flnxi-material:standard-$(date +%Y%m%d)

# 推送到仓库
docker push your-registry.com:5000/flnxi-material:standard-latest
docker push your-registry.com:5000/flnxi-material:standard-$(date +%Y%m%d)
```

#### 2.2 构建Pro版镜像

```bash
# Pro版使用相同的Dockerfile，但通过环境变量区分
docker build -t your-registry.com:5000/flnxi-material:pro-latest .

# 标记镜像
docker tag your-registry.com:5000/flnxi-material:pro-latest \
  your-registry.com:5000/flnxi-material:pro-$(date +%Y%m%d)

# 推送到仓库
docker push your-registry.com:5000/flnxi-material:pro-latest
docker push your-registry.com:5000/flnxi-material:pro-$(date +%Y%m%d)
```

### 3. 客户服务器配置

#### 3.1 配置镜像仓库地址

**在客户服务器上配置**（`/etc/docker/daemon.json`）：
```json
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ],
  "insecure-registries": [
    "your-registry.com:5000"
  ]
}
```

**如果使用HTTPS**，移除 `insecure-registries`，配置证书：
```bash
# 复制证书到客户服务器
scp your-registry.com:/etc/docker/registry/domain.crt /etc/docker/certs.d/your-registry.com:5000/ca.crt

# 重启Docker
sudo systemctl restart docker
```

#### 3.2 配置环境变量

**创建 `.env` 文件**：
```bash
# Docker镜像仓库地址
DOCKER_REGISTRY=your-registry.com:5000

# 镜像标签
IMAGE_TAG=latest

# 服务器IP
SERVER_IP=客户服务器IP

# 数据库密码（建议修改）
POSTGRES_PASSWORD=your-secure-password

# MinIO密码（Pro版需要）
MINIO_ROOT_PASSWORD=your-secure-password
```

### 4. 部署标准版

```bash
# 1. 上传配置文件
scp docker-compose.standard.yml root@客户服务器:/root/deploy/
scp .env root@客户服务器:/root/deploy/

# 2. SSH登录客户服务器
ssh root@客户服务器

# 3. 配置Docker镜像加速器
bash scripts/server/setup-docker-mirror.sh

# 4. 部署
cd /root/deploy
docker compose -f docker-compose.standard.yml --env-file .env up -d
```

### 5. 升级到Pro版

#### 方式1：使用升级脚本（推荐）

**PowerShell（Windows）**：
```powershell
.\scripts\deploy\upgrade-to-pro.ps1 `
  -Server 客户服务器IP `
  -DockerRegistry your-registry.com:5000 `
  -ImageTag latest
```

**Bash（Linux）**：
```bash
export DOCKER_REGISTRY=your-registry.com:5000
export IMAGE_TAG=latest
bash scripts/deploy/upgrade-to-pro.sh
```

#### 方式2：手动升级

```bash
# 1. 备份
cd /root/deploy
mkdir -p backup
cp docker-compose.yml backup/
docker compose exec -T postgres pg_dump -U postgres flnxi > backup/db.sql

# 2. 停止服务
docker compose down

# 3. 切换配置
ln -sf docker-compose.prod.yml docker-compose.yml

# 4. 更新环境变量
echo "DOCKER_REGISTRY=your-registry.com:5000" >> .env
echo "IMAGE_TAG=latest" >> .env

# 5. 拉取镜像
docker pull your-registry.com:5000/flnxi-material:pro-latest
docker pull minio/minio:RELEASE.2025-04-22T22-12-26Z
docker pull minio/mc:RELEASE.2025-04-22T22-12-26Z

# 6. 启动服务
docker compose --env-file .env up -d
```

---

## 🔒 安全配置

### 1. 镜像仓库认证

**启用认证**：
```bash
# 创建认证文件
mkdir -p /auth
docker run --entrypoint htpasswd httpd:2 \
  -Bbn username password > /auth/htpasswd

# 使用认证运行Registry
docker run -d \
  --name docker-registry \
  -p 5000:5000 \
  -v /auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  registry:2
```

**客户服务器登录**：
```bash
docker login your-registry.com:5000
# 输入用户名和密码
```

### 2. 网络隔离

- 使用内网部署Registry
- 配置防火墙规则
- 使用VPN访问（如需要）

---

## 📝 版本管理

### 镜像标签策略

```
标准版：
- standard-latest        # 最新版本
- standard-20251115      # 日期版本
- standard-v1.0.0        # 语义版本

Pro版：
- pro-latest            # 最新版本
- pro-20251115          # 日期版本
- pro-v1.0.0            # 语义版本
```

### 更新流程

1. **构建新镜像**
2. **推送到仓库**（保留旧版本）
3. **在测试环境验证**
4. **通知客户更新**
5. **客户执行升级脚本**

---

## ✅ 检查清单

### 镜像仓库配置
- [ ] Registry服务已部署
- [ ] HTTPS证书已配置（生产环境）
- [ ] 认证已启用（如需要）
- [ ] 镜像已构建并推送

### 客户服务器配置
- [ ] Docker镜像加速器已配置
- [ ] 镜像仓库地址已配置
- [ ] 证书已安装（HTTPS）
- [ ] 环境变量已设置

### 部署验证
- [ ] 标准版部署成功
- [ ] 应用可以正常访问
- [ ] 数据存储正常
- [ ] 升级到Pro版成功

---

## 🐛 故障排查

### 问题1：无法拉取镜像
**原因**：镜像仓库地址配置错误或网络问题

**解决**：
```bash
# 检查配置
docker info | grep -A 10 "Insecure Registries"

# 测试连接
curl -k https://your-registry.com:5000/v2/

# 检查DNS
nslookup your-registry.com
```

### 问题2：认证失败
**原因**：未登录或凭证错误

**解决**：
```bash
# 重新登录
docker login your-registry.com:5000

# 检查凭证
cat ~/.docker/config.json
```

### 问题3：升级失败
**原因**：配置错误或镜像不存在

**解决**：
```bash
# 检查镜像是否存在
docker pull your-registry.com:5000/flnxi-material:pro-latest

# 检查配置文件
cat docker-compose.prod.yml | grep image

# 查看日志
docker compose logs
```

---

**最后更新**：2025-11-15