整理仓库：扩展 gitignore、归档文档、清理冗余 Dockerfile

- .gitignore 新增忽略 .idea/、videos/、*.tar.gz、*.csproj.user、db 运行时文件 - 根目录 15 个中文运维 md 归档到 docs/ - 删除无部署脚本引用的 Dockerfile 与 Dockerfile-arm（保留 Dockerfile.prod） Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 21:28:41 +08:00
parent af40ed69fc
commit ad97fd3da5
18 changed files with 3811 additions and 21 deletions
@@ -0,0 +1,368 @@
+# 镜像构建和推送指南
+
+本文档说明如何构建 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
+
+