flnxi-Wu/一键部署完整指南.md

一键部署完整指南

🎯 目标

让其他公司能够一条命令完成部署，无需源码，直接从私有镜像仓库拉取镜像。

---

📦 部署前准备

1. 服务器要求

• ✅ Linux服务器（推荐Ubuntu 20.04+或CentOS 7+）
• ✅ Docker 20.10+
• ✅ Docker Compose 2.0+
• ✅ 至少2GB内存
• ✅ 至少20GB磁盘空间

2. 配置Docker镜像加速器（必须）

执行配置脚本：

# 上传脚本到服务器
scp scripts/server/setup-docker-mirror.sh root@服务器IP:/root/

# SSH登录服务器
ssh root@服务器IP

# 执行配置
chmod +x /root/setup-docker-mirror.sh
sudo /root/setup-docker-mirror.sh

或手动配置：

# 创建配置文件
sudo nano /etc/docker/daemon.json

# 添加内容
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}

# 重启Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

---

🚀 标准版部署（内网使用）

方式1：一键部署脚本

在本地执行（需要提供镜像仓库地址）：

# Windows PowerShell
.\scripts\deploy\local-build-and-upload.ps1 `
  -Server 服务器IP `
  -Username root `
  -Password 密码 `
  -DockerRegistry 你的镜像仓库地址:5000 `
  -Edition standard

方式2：手动部署

步骤1：上传配置文件

# 上传标准版配置
scp docker-compose.standard.yml root@服务器IP:/root/deploy/

步骤2：创建环境变量文件

# SSH登录服务器
ssh root@服务器IP

# 创建.env文件
cd /root/deploy
cat > .env << EOF
# Docker镜像仓库（必须配置）
DOCKER_REGISTRY=你的镜像仓库地址:5000

# 镜像标签
IMAGE_TAG=latest

# 服务器IP
SERVER_IP=服务器IP地址

# 数据库配置
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=youyidian3d

# 应用端口
APP_PORT=4320

# NextAuth密钥（必须修改）
NEXTAUTH_SECRET=$(openssl rand -base64 32)
EOF

步骤3：部署

# 拉取镜像（自动使用国内镜像源）
docker compose -f docker-compose.standard.yml --env-file .env pull

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

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

步骤4：创建配置链接

# 创建docker-compose.yml链接（方便后续操作）
ln -sf docker-compose.standard.yml docker-compose.yml

---

🚀 Pro版部署（支持内网穿透）

方式1：从标准版升级（推荐）

使用升级脚本：

# Windows PowerShell
.\scripts\deploy\upgrade-to-pro.ps1 `
  -Server 服务器IP `
  -DockerRegistry 你的镜像仓库地址:5000 `
  -ImageTag latest

或Linux服务器上直接执行：

export DOCKER_REGISTRY=你的镜像仓库地址:5000
export IMAGE_TAG=latest
bash scripts/deploy/upgrade-to-pro.sh

方式2：直接部署Pro版

步骤1：上传配置文件

scp docker-compose.prod.yml root@服务器IP:/root/deploy/

步骤2：创建环境变量文件

cd /root/deploy
cat > .env << EOF
# Docker镜像仓库
DOCKER_REGISTRY=你的镜像仓库地址:5000
IMAGE_TAG=latest

# 服务器IP
SERVER_IP=服务器IP地址

# 数据库配置
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=youyidian3d

# MinIO配置（Pro版需要）
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password
S3_BUCKET=youyidian3d
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001

# 应用配置
APP_PORT=4320
NEXTAUTH_SECRET=$(openssl rand -base64 32)
EOF

步骤3：部署

# 拉取所有镜像
docker compose -f docker-compose.prod.yml --env-file .env pull

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

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

---

🔄 版本升级

升级应用镜像

# 拉取新版本镜像
docker pull 你的镜像仓库地址:5000/youyidian-3d-material:standard-latest

# 重启服务
cd /root/deploy
docker compose pull
docker compose up -d

从标准版升级到Pro版

使用升级脚本（推荐）：

export DOCKER_REGISTRY=你的镜像仓库地址:5000
bash scripts/deploy/upgrade-to-pro.sh

手动升级：

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

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

# 3. 更新环境变量
echo "DOCKER_REGISTRY=你的镜像仓库地址:5000" >> .env

# 4. 拉取Pro版镜像和MinIO
docker pull 你的镜像仓库地址:5000/youyidian-3d-material:pro-latest
docker pull minio/minio:RELEASE.2025-04-22T22-12-26Z
docker pull minio/mc:RELEASE.2025-04-22T22-12-26Z

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

---

✅ 部署验证

检查服务状态

cd /root/deploy
docker compose ps

预期输出：

NAME                    STATUS
youyidian-postgres      Up (healthy)
youyidian-3d-material   Up (healthy)
youyidian-minio         Up (healthy)  # Pro版才有

检查应用健康

# 健康检查
curl http://localhost:4320/api/health

# 预期输出
{"status":"ok","timestamp":"..."}

访问应用

• 应用地址：http://服务器IP:4320
• MinIO控制台（Pro版）：http://服务器IP:9001
• 默认账号：
  • MinIO: minioadmin / minioadmin123456（建议修改）

---

🔧 常用操作

查看日志

# 查看所有服务日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f app
docker compose logs -f minio  # Pro版

停止服务

docker compose down

重启服务

docker compose restart

备份数据

# 备份数据库
docker compose exec -T postgres pg_dump -U postgres youyidian3d > backup_$(date +%Y%m%d).sql

# 备份上传文件（标准版）
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz ./uploads

# 备份MinIO数据（Pro版）
docker run --rm -v youyidian-minio_data:/data -v $(pwd):/backup \
  alpine tar -czf /backup/minio_backup_$(date +%Y%m%d).tar.gz /data

---

🐛 故障排查

问题1：无法拉取镜像

检查项：

# 检查镜像仓库配置
docker info | grep -A 10 "Insecure Registries"

# 测试连接
curl -k https://你的镜像仓库地址:5000/v2/

# 检查登录状态
docker login 你的镜像仓库地址:5000

问题2：服务启动失败

检查项：

# 查看详细日志
docker compose logs

# 检查端口占用
netstat -tlnp | grep -E "4320|9000|9001|5432"

# 检查磁盘空间
df -h

问题3：升级失败

解决：

# 回滚到备份
cd /root/deploy
cp backup/docker-compose.yml docker-compose.yml
docker compose up -d

# 恢复数据库
docker compose exec -T postgres psql -U postgres youyidian3d < backup/db.sql

---

📝 注意事项

1. 安全性：

   • ✅ 修改所有默认密码
   • ✅ 使用HTTPS访问镜像仓库（生产环境）
   • ✅ 配置防火墙规则

2. 性能：

   • ✅ 确保配置了Docker镜像加速器
   • ✅ 定期清理未使用的镜像：docker system prune -a

3. 备份：

   • ✅ 定期备份数据库
   • ✅ 备份上传文件和MinIO数据

---

最后更新：2025-11-15