dysync/docs/飞牛NAS部署完整指南.md

飞牛 NAS 部署完整指南

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

---

📋 目录

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

---

🔧 环境准备

本地电脑（Mac）

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

飞牛 NAS 环境

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

---

📤 上传项目文件到 NAS

步骤 1：压缩项目文件

在本地电脑上执行：

# 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

# 上传到 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 后执行：

# 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 自带镜像源，通常无需配置。如果遇到网络问题，可以配置：

# 创建 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：手动拉取基础镜像（推荐）

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

# 拉取所需的基础镜像
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 配置正确：

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

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

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

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

# 修复 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，确保包含国内镜像源配置：

sudo nano Dockerfile.prod

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

# 配置 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 . . 之后添加：

sudo nano Dockerfile.prod

在 COPY . . 之后添加：

# 复制所有文件
COPY . .

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

步骤 4：更新 .dockerignore

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

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

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

# 验证
tail -5 .dockerignore

步骤 5：构建 Docker 镜像

# 确保在项目目录
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 文件存在且配置正确：

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

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

配置文件应该类似这样：

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：创建数据目录

# 创建必要的数据目录
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：启动容器

# 确保在项目目录
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 命令都不存在，可以直接运行容器：

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：检查容器状态

# 查看容器是否运行
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）：

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

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

成功标志：

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

---

🛠️ 常用管理命令

容器管理

# 停止容器
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

日志管理

# 查看日志
sudo docker logs dysync

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

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

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

使用 docker-compose 管理

# 启动服务
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

镜像管理

# 查看所有镜像
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：容器无法启动

检查步骤：

# 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：服务无法访问

检查步骤：

# 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 错误

解决方案：

# 修复 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 确保容器自动重启

恢复数据：

# 检查数据目录
ls -la /vol2/1000/docker/dysync/db/

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

---

📝 更新部署

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

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

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

# 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 上更新文件并重新部署

# 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：

#!/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 "更新完成！"

使用方法：

chmod +x update.sh
./update.sh

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

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

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

# 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 上拉取并更新

# 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

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

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

# 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

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

---

🎯 快速参考

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

#!/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

---

📚 相关文档

• 本地启动指南
• 网络问题解决方案
• 构建问题排查

---

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