# 飞牛 NAS 部署完整指南

本文档提供在飞牛 NAS 上部署 dysync.net 项目的完整步骤，包括环境准备、文件上传、镜像构建、容器部署和故障排查。

---

## 📋 目录

1. [环境准备](#环境准备)
2. [上传项目文件到 NAS](#上传项目文件到-nas)
3. [在 NAS 上构建 Docker 镜像](#在-nas-上构建-docker-镜像)
4. [配置和部署容器](#配置和部署容器)
5. [验证服务](#验证服务)
6. [常用管理命令](#常用管理命令)
7. [故障排查](#故障排查)
8. [更新部署](#更新部署)

---

## 🔧 环境准备

### 本地电脑（Mac）

1. **SSH 客户端**（macOS 自带，无需安装）
2. **项目文件**：确保项目代码已准备好

### 飞牛 NAS 环境

- Docker 已安装并运行
- SSH 服务已启用
- 有足够的磁盘空间（建议至少 10GB）
- 已创建项目目录：`/vol2/1000/docker/dysync`

---

## 📤 上传项目文件到 NAS

### 步骤 1：压缩项目文件

在本地电脑上执行：

```bash
# 1. 进入项目根目录
cd /Users/gaotu/WebstormProjects/dysync.net

# 2. 压缩项目文件（排除不必要的文件）
# 注意：将压缩文件输出到父目录，避免包含压缩文件本身
tar -czf ../dysync.net.tar.gz \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='app/node_modules' \
  --exclude='bin' \
  --exclude='obj' \
  --exclude='.vs' \
  --exclude='.idea' \
  --exclude='videos' \
  --exclude='*.md' \
  --exclude='docs' \
  --exclude='*.tar.gz' \
  .
```

### 步骤 2：上传到 NAS

```bash
# 上传到 NAS（替换为你的 NAS IP 和用户名）
scp ../dysync.net.tar.gz 你的用户名@NAS_IP:/vol2/1000/docker/dysync/

# 示例
scp ../dysync.net.tar.gz adminym@192.168.1.99:/vol2/1000/docker/dysync/
```

### 步骤 3：在 NAS 上解压文件

SSH 连接到 NAS 后执行：

```bash
# 1. 进入目录
cd /vol2/1000/docker/dysync

# 2. 创建项目文件夹并解压
mkdir -p dysync.net
tar -xzf dysync.net.tar.gz -C dysync.net/

# 3. 验证文件已解压
ls -la dysync.net/
```

**注意**：解压时可能会看到很多 `tar: Ignoring unknown extended header keyword` 警告，这是正常的，不影响文件解压。

---

## 🐳 在 NAS 上构建 Docker 镜像

### 步骤 1：配置 Docker 镜像加速器（可选）

飞牛 NAS 自带镜像源，通常无需配置。如果遇到网络问题，可以配置：

```bash
# 创建 Docker 配置目录
sudo mkdir -p /etc/docker

# 创建镜像加速器配置
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.cn-hangzhou.aliyuncs.com"
  ]
}
EOF

# 重启 Docker 服务
sudo systemctl restart docker
sleep 5
```

### 步骤 2：手动拉取基础镜像（推荐）

避免构建时网络问题，先手动拉取：

```bash
# 拉取所需的基础镜像
sudo docker pull node:18-alpine
sudo docker pull mcr.microsoft.com/dotnet/sdk:6.0
sudo docker pull mcr.microsoft.com/dotnet/aspnet:6.0

# 验证镜像已拉取
sudo docker images | grep -E "node|dotnet"
```

### 步骤 3：检查并修复 Dockerfile

确保 Dockerfile.prod 配置正确：

```bash
cd /vol2/1000/docker/dysync/dysync.net

# 检查 Dockerfile.prod 是否存在
ls -la Dockerfile.prod

# 检查关键配置
cat Dockerfile.prod | grep -E "dotnet restore|dotnet publish"
```

**重要修复**：如果 Dockerfile 中缺少项目文件指定，需要修复：

```bash
# 修复 dotnet restore 命令
sudo sed -i 's/RUN dotnet restore/RUN dotnet restore dy.net.csproj/' Dockerfile.prod

# 修复 dotnet publish 命令
sudo sed -i 's/RUN dotnet publish -c Release -o \/app\/publish/RUN dotnet publish dy.net.csproj -c Release -o \/app\/publish/' Dockerfile.prod
```

**配置 npm/pnpm 镜像源**：编辑 Dockerfile.prod，确保包含国内镜像源配置：

```bash
sudo nano Dockerfile.prod
```

找到前端构建部分（约第 10-18 行），确保格式如下：

```dockerfile
# 配置 npm 和 pnpm 使用国内镜像源
RUN npm config set registry https://registry.npmmirror.com && \
    npm install -g pnpm && \
    pnpm config set registry https://registry.npmmirror.com && \
    if [ -f pnpm-lock.yaml ]; then \
      pnpm install --frozen-lockfile; \
    else \
      npm install; \
    fi
```

**添加删除 macOS 资源分叉文件的步骤**：在 Dockerfile.prod 的 `COPY . .` 之后添加：

```bash
sudo nano Dockerfile.prod
```

在 `COPY . .` 之后添加：

```dockerfile
# 复制所有文件
COPY . .

# 删除 macOS 资源分叉文件（._* 文件）
RUN find . -name "._*" -type f -delete
```

### 步骤 4：更新 .dockerignore

确保排除 macOS 资源分叉文件：

```bash
cd /vol2/1000/docker/dysync/dysync.net

# 添加排除规则
echo "._*" >> .dockerignore

# 验证
tail -5 .dockerignore
```

### 步骤 5：构建 Docker 镜像

```bash
# 确保在项目目录
cd /vol2/1000/docker/dysync/dysync.net

# 构建镜像（这可能需要 10-30 分钟）
sudo docker build -f Dockerfile.prod -t dysync.net:latest .

# 验证镜像构建成功
sudo docker images | grep dysync
```

**构建成功标志**：
```
Successfully built abc123def456
Successfully tagged dysync.net:latest
```

---

## ⚙️ 配置和部署容器

### 步骤 1：配置 docker-compose 文件

确保 docker-compose.feiniu.vol2.yml 文件存在且配置正确：

```bash
cd /vol2/1000/docker/dysync/dysync.net

# 查看配置文件
cat docker-compose.feiniu.vol2.yml
```

配置文件应该类似这样：

```yaml
version: '3.8'

services:
  dysync:
    image: dysync.net:latest
    container_name: dysync
    restart: always
    ports:
      - "10101:10101"
    volumes:
      # 数据库目录（必须配置，防止数据丢失）
      - /vol2/1000/docker/dysync/db:/app/db
      # 收藏视频目录
      - /vol2/1000/docker/dysync/collect:/app/collect
      # 喜欢视频目录
      - /vol2/1000/docker/dysync/favorite:/app/favorite
      # 博主视频目录（可选）
      - /vol2/1000/docker/dysync/uper:/app/uper
      # 日志目录（可选，方便查看日志）
      - /vol2/1000/docker/dysync/logs:/app/logs
    environment:
      - TZ=Asia/Shanghai
      - ASPNETCORE_ENVIRONMENT=Production
    # 配置DNS服务器（解决域名解析失败导致的无法访问外网）
    dns:
      - 8.8.8.8          # Google DNS
      - 114.114.114.114  # 国内DNS
      - 223.5.5.5        # 阿里DNS
    # 网络模式
    network_mode: bridge
```

### 步骤 2：创建数据目录

```bash
# 创建必要的数据目录
sudo mkdir -p /vol2/1000/docker/dysync/{db,collect,favorite,uper,logs}

# 设置目录权限（确保容器可以读写）
sudo chmod -R 755 /vol2/1000/docker/dysync

# 验证目录创建成功
ls -la /vol2/1000/docker/dysync/
```

### 步骤 3：启动容器

```bash
# 确保在项目目录
cd /vol2/1000/docker/dysync/dysync.net

# 使用 docker compose 启动容器（推荐）
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 如果上面的命令不存在，尝试：
sudo docker-compose -f docker-compose.feiniu.vol2.yml up -d
```

**启动成功标志**：
```
[+] Running 1/1
 ✔ Container dysync  Started
```

如果 docker-compose 命令都不存在，可以直接运行容器：

```bash
sudo docker run -d \
  --name dysync \
  -p 10101:10101 \
  -v /vol2/1000/docker/dysync/db:/app/db \
  -v /vol2/1000/docker/dysync/collect:/app/collect \
  -v /vol2/1000/docker/dysync/favorite:/app/favorite \
  -v /vol2/1000/docker/dysync/uper:/app/uper \
  -v /vol2/1000/docker/dysync/logs:/app/logs \
  --restart always \
  --dns 8.8.8.8 \
  --dns 114.114.114.114 \
  --dns 223.5.5.5 \
  -e TZ=Asia/Shanghai \
  -e ASPNETCORE_ENVIRONMENT=Production \
  dysync.net:latest
```

---

## ✅ 验证服务

### 步骤 1：检查容器状态

```bash
# 查看容器是否运行
sudo docker ps | grep dysync

# 查看容器详细信息
sudo docker ps -a | grep dysync

# 查看容器日志（检查服务是否正常启动）
sudo docker logs dysync

# 如果日志很多，只看最后50行
sudo docker logs --tail 50 dysync

# 实时查看日志（按 Ctrl+C 退出）
sudo docker logs -f dysync
```

### 步骤 2：测试服务访问

**在本地电脑上测试**（不是 NAS）：

```bash
# 测试服务是否可访问（替换为你的 NAS IP）
curl http://你的NAS_IP:10101

# 或者在浏览器中访问
# http://你的NAS_IP:10101
```

**成功标志**：
- 容器状态显示 `Up` 或 `running`
- 日志中看到类似 `Now listening on: http://[::]:10101` 的信息
- 浏览器可以访问服务页面

---

## 🛠️ 常用管理命令

### 容器管理

```bash
# 停止容器
sudo docker stop dysync

# 启动容器
sudo docker start dysync

# 重启容器
sudo docker restart dysync

# 删除容器（需要先停止）
sudo docker stop dysync
sudo docker rm dysync

# 查看容器资源使用情况
sudo docker stats dysync

# 进入容器内部（调试用）
sudo docker exec -it dysync /bin/bash
```

### 日志管理

```bash
# 查看日志
sudo docker logs dysync

# 查看最后 N 行日志
sudo docker logs --tail 100 dysync

# 实时查看日志
sudo docker logs -f dysync

# 查看日志并包含时间戳
sudo docker logs -t dysync
```

### 使用 docker-compose 管理

```bash
# 启动服务
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 停止服务
sudo docker compose -f docker-compose.feiniu.vol2.yml down

# 重启服务
sudo docker compose -f docker-compose.feiniu.vol2.yml restart

# 查看服务状态
sudo docker compose -f docker-compose.feiniu.vol2.yml ps

# 查看日志
sudo docker compose -f docker-compose.feiniu.vol2.yml logs -f
```

### 镜像管理

```bash
# 查看所有镜像
sudo docker images

# 删除镜像
sudo docker rmi dysync.net:latest

# 重新构建镜像（更新代码后）
cd /vol2/1000/docker/dysync/dysync.net
sudo docker build -f Dockerfile.prod -t dysync.net:latest .
```

---

## 🔍 故障排查

### 问题 1：容器无法启动

**检查步骤**：
```bash
# 1. 查看容器状态
sudo docker ps -a | grep dysync

# 2. 查看详细日志
sudo docker logs dysync

# 3. 检查端口是否被占用
sudo netstat -tulpn | grep 10101

# 4. 检查目录权限
ls -la /vol2/1000/docker/dysync/
```

**常见原因**：
- 端口被占用：修改 `docker-compose.feiniu.vol2.yml` 中的端口映射
- 目录权限不足：执行 `sudo chmod -R 755 /vol2/1000/docker/dysync`
- 镜像不存在：重新构建镜像

### 问题 2：服务无法访问

**检查步骤**：
```bash
# 1. 检查容器是否运行
sudo docker ps | grep dysync

# 2. 检查端口映射
sudo docker port dysync

# 3. 检查防火墙设置（在 NAS 管理界面）
# 4. 检查网络连接
ping 你的NAS_IP
```

**常见原因**：
- 防火墙阻止：在 NAS 管理界面开放 10101 端口
- 容器未启动：执行 `sudo docker start dysync`
- 网络问题：检查 NAS 网络配置

### 问题 3：构建镜像失败

#### 3.1 网络超时问题

**症状**：构建时出现 `ERR_SOCKET_TIMEOUT` 或 `ECONNRESET` 错误

**解决方案**：
1. 确保 Dockerfile.prod 中配置了 npm/pnpm 镜像源
2. 手动拉取基础镜像后再构建
3. 配置 Docker 镜像加速器

#### 3.2 macOS 资源分叉文件问题

**症状**：构建时出现 `CS2015: '._xxx.cs' is a binary file instead of a text file` 错误

**解决方案**：
1. 在 `.dockerignore` 中添加 `._*`
2. 在 Dockerfile.prod 中添加删除步骤：`RUN find . -name "._*" -type f -delete`

#### 3.3 dotnet 命令缺少项目文件

**症状**：构建时出现 `MSB1011: Specify which project or solution file to use` 错误

**解决方案**：
```bash
# 修复 Dockerfile.prod
sudo sed -i 's/RUN dotnet restore/RUN dotnet restore dy.net.csproj/' Dockerfile.prod
sudo sed -i 's/RUN dotnet publish -c Release -o \/app\/publish/RUN dotnet publish dy.net.csproj -c Release -o \/app\/publish/' Dockerfile.prod
```

### 问题 4：数据丢失

**预防措施**：
- 确保所有数据目录都正确挂载到宿主机
- 定期备份 `/vol2/1000/docker/dysync/db` 目录
- 使用 `--restart always` 确保容器自动重启

**恢复数据**：
```bash
# 检查数据目录
ls -la /vol2/1000/docker/dysync/db/

# 如果有备份，恢复备份
# cp -r /backup/db/* /vol2/1000/docker/dysync/db/
```

---

## 📝 更新部署

当本地项目修改后，需要重新部署到 NAS。以下是完整的更新流程：

### 方法一：重新构建镜像（推荐，适合代码修改）

#### 步骤 1：在本地压缩并上传新版本

```bash
# 1. 在本地电脑上，进入项目根目录
cd /Users/gaotu/WebstormProjects/dysync.net

# 2. 压缩项目文件（排除不必要的文件）
tar -czf ../dysync.net.tar.gz \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='app/node_modules' \
  --exclude='bin' \
  --exclude='obj' \
  --exclude='.vs' \
  --exclude='.idea' \
  --exclude='videos' \
  --exclude='*.md' \
  --exclude='docs' \
  --exclude='*.tar.gz' \
  .

# 3. 上传到 NAS（替换为你的实际信息）
scp ../dysync.net.tar.gz 你的用户名@NAS_IP:/vol2/1000/docker/dysync/
# 示例：scp ../dysync.net.tar.gz adminym@192.168.1.99:/vol2/1000/docker/dysync/
```

#### 步骤 2：在 NAS 上更新文件并重新部署

```bash
# 1. SSH 连接到 NAS
ssh 你的用户名@NAS_IP
# 示例：ssh adminym@192.168.1.99

# 2. 进入项目目录
cd /vol2/1000/docker/dysync

# 3. 备份旧版本（可选，建议）
mv dysync.net dysync.net.backup.$(date +%Y%m%d_%H%M%S)

# 4. 创建新的项目目录并解压
mkdir -p dysync.net
tar -xzf dysync.net.tar.gz -C dysync.net/

# 5. 停止并删除旧容器
cd dysync.net
sudo docker compose -f docker-compose.feiniu.vol2.yml down
# 或者如果容器名称是 dysync：
# sudo docker stop dysync && sudo docker rm dysync

# 6. 删除旧镜像（可选，释放空间）
sudo docker rmi dysync.net:latest

# 7. 重新构建镜像
sudo docker build -f Dockerfile.prod -t dysync.net:latest .

# 8. 启动新容器
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 9. 验证服务
sudo docker ps | grep dysync
sudo docker logs --tail 50 dysync
```

#### 一键更新脚本（可选）

你也可以创建一个更新脚本 `update.sh`：

```bash
#!/bin/bash
# 更新部署脚本

set -e

echo "开始更新部署..."

# 1. 停止并删除旧容器
echo "停止旧容器..."
sudo docker compose -f docker-compose.feiniu.vol2.yml down || true

# 2. 删除旧镜像（可选）
read -p "是否删除旧镜像以释放空间？(y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    sudo docker rmi dysync.net:latest || true
fi

# 3. 重新构建镜像
echo "构建新镜像..."
sudo docker build -f Dockerfile.prod -t dysync.net:latest .

# 4. 启动新容器
echo "启动新容器..."
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 5. 查看日志
echo "查看容器日志..."
sleep 3
sudo docker logs --tail 50 dysync

echo "更新完成！"
```

使用方法：
```bash
chmod +x update.sh
./update.sh
```

### 方法二：推送到镜像仓库后拉取（适合频繁更新）

如果你有镜像仓库访问权限，可以使用这种方式：

#### 步骤 1：在本地构建并推送

```bash
# 1. 在本地电脑上，进入项目根目录
cd /Users/gaotu/WebstormProjects/dysync.net

# 2. 构建镜像并打标签
docker build -f Dockerfile.prod -t registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest .

# 3. 登录镜像仓库（如果还没登录）
docker login registry.cn-hangzhou.aliyuncs.com

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

#### 步骤 2：在 NAS 上拉取并更新

```bash
# 1. SSH 连接到 NAS
ssh 你的用户名@NAS_IP

# 2. 停止旧容器
cd /vol2/1000/docker/dysync/dysync.net
sudo docker compose -f docker-compose.feiniu.vol2.yml down

# 3. 拉取新镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 4. 更新 docker-compose.feiniu.vol2.yml 中的镜像地址（如果还没更新）
sudo sed -i 's|image: dysync.net:latest|image: registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest|g' docker-compose.feiniu.vol2.yml

# 5. 启动新容器
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 6. 验证服务
sudo docker ps | grep dysync
sudo docker logs --tail 50 dysync
```

### 方法三：仅更新代码文件（快速更新，不重新构建镜像）

如果只是修改了配置文件或少量代码，可以只更新文件：

```bash
# 1. 在本地压缩修改的文件
tar -czf ../update.tar.gz 修改的文件或目录

# 2. 上传到 NAS
scp ../update.tar.gz 你的用户名@NAS_IP:/vol2/1000/docker/dysync/

# 3. SSH 连接到 NAS
ssh 你的用户名@NAS_IP

# 4. 进入容器并更新文件
cd /vol2/1000/docker/dysync
tar -xzf update.tar.gz -C dysync.net/

# 5. 重启容器使更改生效
sudo docker restart dysync
```

**注意**：这种方法只适用于不需要重新编译的更改（如配置文件）。对于代码修改，建议使用方法一重新构建镜像。

---

## 🎯 快速参考

### 完整部署命令（一键执行脚本）

```bash
#!/bin/bash
# 快速部署脚本

# 1. 进入项目目录
cd /vol2/1000/docker/dysync/dysync.net

# 2. 构建镜像
sudo docker build -f Dockerfile.prod -t dysync.net:latest .

# 3. 创建数据目录
sudo mkdir -p /vol2/1000/docker/dysync/{db,collect,favorite,uper,logs}
sudo chmod -R 755 /vol2/1000/docker/dysync

# 4. 启动容器
sudo docker compose -f docker-compose.feiniu.vol2.yml up -d

# 5. 查看日志
sudo docker logs -f dysync
```

### 关键路径和端口

- **项目路径**：`/vol2/1000/docker/dysync`
- **数据目录**：`/vol2/1000/docker/dysync/{db,collect,favorite,uper,logs}`
- **服务端口**：`10101`
- **访问地址**：`http://你的NAS_IP:10101`

---

## 📚 相关文档

- [本地启动指南](./本地启动指南.md)
- [网络问题解决方案](./网络问题解决方案.md)
- [构建问题排查](./构建问题排查.md)

---

**最后更新**：2024-12-17  
**适用系统**：飞牛 NAS（Linux x86_64）  
**Docker 版本**：28.5.2  
**项目路径**：`/vol2/1000/docker/dysync`