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

# 镜像构建和推送指南

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

## 📋 目录

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

---

## 🔧 前提条件

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

- 注册 [阿里云账号](https://www.aliyun.com/)
- 开通 [容器镜像服务](https://cr.console.aliyun.com/)
- 创建命名空间（如：`jianzhichu`）
- 创建镜像仓库（如：`dysync.net`）

### 2. 获取登录凭证

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

---

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

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

### 检查镜像是否存在

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

### 如果镜像存在

直接在飞牛 NAS 上拉取：

```bash
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 构建镜像

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

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

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

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

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

#### 1.3 验证镜像

```bash
# 查看镜像
docker images | grep dysync

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

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

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

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

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

### 步骤 3：标记镜像

```bash
# 标记镜像（替换为你的实际仓库地址）
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：推送镜像

```bash
# 推送 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 上拉取：

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

---

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

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

### 步骤 1：上传项目文件

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

### 步骤 2：SSH 连接到飞牛 NAS

```bash
ssh admin@你的飞牛NAS IP
```

### 步骤 3：构建镜像

```bash
# 进入项目目录
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`：

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

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

---

## 🔄 完整流程示例

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

```bash
# 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
```

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

```bash
# 直接在飞牛 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
```

**解决方案：**
```bash
# 重新登录
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. 构建失败

**问题：前端构建失败**

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

**问题：后端构建失败**

```bash
# 清除构建缓存
dotnet clean
dotnet restore
```

---

## 📝 快速参考

### 检查镜像是否存在

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

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

### 完整构建和推送命令

```bash
# 一键构建和推送脚本
#!/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