dysync/docs/镜像构建和推送指南.md

镜像构建和推送指南

本文档说明如何构建 Docker 镜像并推送到阿里云容器镜像服务，以便在飞牛 NAS 上使用。

📋 目录

1. 前提条件
2. 方式一：使用现有镜像（最简单）
3. 方式二：构建并推送镜像
4. 方式三：本地构建直接使用
5. 常见问题

---

🔧 前提条件

1. 阿里云容器镜像服务账号

• 注册 阿里云账号
• 开通 容器镜像服务
• 创建命名空间（如：jianzhichu）
• 创建镜像仓库（如：dysync.net）

2. 获取登录凭证

1. 登录阿里云容器镜像服务控制台
2. 进入「访问凭证」
3. 设置固定密码或临时密码
4. 记录用户名和密码

---

✅ 方式一：使用现有镜像（最简单）

如果镜像仓库中已经有镜像，直接拉取即可，无需上传！

检查镜像是否存在

1. 访问：https://cr.console.aliyun.com/
2. 进入你的命名空间
3. 查看是否有 dysync.net 仓库
4. 查看是否有 latest 标签的镜像

如果镜像存在

直接在飞牛 NAS 上拉取：

docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

无需任何上传操作！

---

🏗️ 方式二：构建并推送镜像

如果你修改了代码，或者镜像不存在，需要自己构建并推送。

步骤 1：在本地构建镜像

1.1 准备构建环境

确保本地已安装：

• Docker Desktop（Mac/Windows）或 Docker Engine（Linux）
• .NET SDK 6.0（可选，如果使用 Dockerfile.prod）
• Node.js 18+（可选，如果使用 Dockerfile.prod）

1.2 构建镜像

使用多阶段构建（推荐）：

# 在项目根目录
docker build -f Dockerfile.prod -t dysync.net:latest .

或使用原始 Dockerfile（需要先构建前端）：

# 1. 先构建前端
cd app
pnpm install
pnpm build
cd ..

# 2. 构建镜像
docker build -t dysync.net:latest .

1.3 验证镜像

# 查看镜像
docker images | grep dysync

# 测试运行（可选）
docker run -d -p 10101:10101 --name dysync-test dysync.net:latest

步骤 2：登录阿里云镜像仓库

# 登录（替换为你的实际信息）
docker login --username=你的用户名 registry.cn-hangzhou.aliyuncs.com

# 输入密码（在阿里云控制台获取）

获取登录信息：

1. 登录阿里云容器镜像服务控制台
2. 点击右上角「访问凭证」
3. 设置固定密码或使用临时密码

步骤 3：标记镜像

# 标记镜像（替换为你的实际仓库地址）
docker tag dysync.net:latest registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 如果构建了 ARM 版本
docker tag dysync.net:arm-latest registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:arm_1.0

步骤 4：推送镜像

# 推送 AMD64 版本
docker push registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 推送 ARM 版本（如果构建了）
docker push registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:arm_1.0

步骤 5：在飞牛 NAS 上拉取

推送成功后，在飞牛 NAS 上拉取：

docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

---

💻 方式三：本地构建直接使用

如果你不想推送到远程仓库，可以在飞牛 NAS 上直接构建。

步骤 1：上传项目文件

1. 将整个项目文件夹上传到飞牛 NAS
2. 建议放在：/volume1/dysync/source/

步骤 2：SSH 连接到飞牛 NAS

ssh admin@你的飞牛NAS IP

步骤 3：构建镜像

# 进入项目目录
cd /volume1/dysync/source

# 构建镜像（使用多阶段构建）
docker build -f Dockerfile.prod -t dysync.net:latest .

# 或使用原始 Dockerfile（需要先构建前端）
cd app
pnpm install  # 或 npm install
pnpm build    # 或 npm run build
cd ..
docker build -t dysync.net:latest .

步骤 4：使用本地镜像

修改 docker-compose.yml：

services:
  dysync:
    image: dysync.net:latest  # 使用本地镜像
    # ... 其他配置

或直接在 Docker 界面中选择本地镜像。

---

🔄 完整流程示例

场景：首次部署，镜像不存在

# 1. 在本地电脑构建镜像
cd /path/to/dysync.net
docker build -f Dockerfile.prod -t dysync.net:latest .

# 2. 登录阿里云
docker login registry.cn-hangzhou.aliyuncs.com

# 3. 标记镜像
docker tag dysync.net:latest registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 4. 推送镜像
docker push registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 5. 在飞牛 NAS 上拉取
ssh admin@飞牛NAS IP
docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 6. 使用 docker-compose 部署
cd /volume1/dysync
docker-compose up -d

场景：使用现有镜像（最简单）

# 直接在飞牛 NAS 上拉取
docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 使用 docker-compose 部署
cd /volume1/dysync
docker-compose up -d

---

🐛 常见问题

1. 镜像拉取失败

问题：镜像不存在

Error response from daemon: pull access denied

解决方案：

• 检查镜像地址是否正确
• 确认镜像是否已推送到仓库
• 如果镜像不存在，需要先构建并推送（方式二）

问题：认证失败

Error response from daemon: unauthorized

解决方案：

# 重新登录
docker logout registry.cn-hangzhou.aliyuncs.com
docker login registry.cn-hangzhou.aliyuncs.com

2. 镜像推送失败

问题：权限不足

denied: requested access to the resource is denied

解决方案：

• 检查命名空间和仓库名称是否正确
• 确认账号有推送权限
• 检查是否已正确登录

问题：网络超时

net/http: TLS handshake timeout

解决方案：

• 检查网络连接
• 使用镜像加速器
• 重试推送

3. 构建失败

问题：前端构建失败

# 清除缓存重新构建
cd app
rm -rf node_modules dist
pnpm install
pnpm build

问题：后端构建失败

# 清除构建缓存
dotnet clean
dotnet restore

---

📝 快速参考

检查镜像是否存在

# 查看本地镜像
docker images | grep dysync

# 尝试拉取（如果失败说明不存在）
docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

完整构建和推送命令

# 一键构建和推送脚本
#!/bin/bash
IMAGE_NAME="dysync.net:latest"
REGISTRY="registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest"

# 构建
docker build -f Dockerfile.prod -t $IMAGE_NAME .

# 登录（需要手动输入密码）
docker login registry.cn-hangzhou.aliyuncs.com

# 标记
docker tag $IMAGE_NAME $REGISTRY

# 推送
docker push $REGISTRY

echo "镜像推送完成: $REGISTRY"

---

💡 推荐方案

方案 A：使用现有镜像（推荐新手）

• ✅ 最简单，无需构建
• ✅ 直接拉取即可使用
• ❌ 无法自定义代码

方案 B：构建并推送（推荐开发者）

• ✅ 可以自定义代码
• ✅ 一次推送，多处使用
• ❌ 需要构建和推送步骤

方案 C：本地构建（推荐私有部署）

• ✅ 完全私有，不依赖外部服务
• ✅ 适合内网环境
• ❌ 需要在每台设备上构建

---

最后更新：2024-11-22
版本：v1.0