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

私有镜像仓库部署指南

📋 概述

本系统支持私有镜像仓库部署，确保：

• ✅ 其他公司使用系统时看不到源码
• ✅ 直接从构建好的镜像服务器下载镜像
• ✅ 所有依赖资源从国内镜像源下载
• ✅ 支持一键从标准版升级到Pro版

---

🏗️ 架构设计

镜像仓库结构

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

部署流程

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

---

🔧 配置步骤

0. 快速部署（推荐）

在 git.1080p.hk 服务器上执行：

# 上传部署脚本
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：使用部署脚本（推荐）

# 在 git.1080p.hk 服务器上执行
bash scripts/server/setup-registry.sh

方式2：手动部署

# 在 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（推荐用于生产环境）

# 上传 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（生产环境必须）

# 生成证书
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 构建标准版镜像

# 构建镜像
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版镜像

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

{
  "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，配置证书：

# 复制证书到客户服务器
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 文件：

# 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. 部署标准版

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

.\scripts\deploy\upgrade-to-pro.ps1 `
  -Server 客户服务器IP `
  -DockerRegistry your-registry.com:5000 `
  -ImageTag latest

Bash（Linux）：

export DOCKER_REGISTRY=your-registry.com:5000
export IMAGE_TAG=latest
bash scripts/deploy/upgrade-to-pro.sh

方式2：手动升级

# 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. 镜像仓库认证

启用认证：

# 创建认证文件
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

客户服务器登录：

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：无法拉取镜像

原因：镜像仓库地址配置错误或网络问题

解决：

# 检查配置
docker info | grep -A 10 "Insecure Registries"

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

# 检查DNS
nslookup your-registry.com

问题2：认证失败

原因：未登录或凭证错误

解决：

# 重新登录
docker login your-registry.com:5000

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

问题3：升级失败

原因：配置错误或镜像不存在

解决：

# 检查镜像是否存在
docker pull your-registry.com:5000/flnxi-material:pro-latest

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

# 查看日志
docker compose logs

---

最后更新：2025-11-15