Files
dysync/docs/飞牛NAS部署完整指南.md
yuming ad97fd3da5 整理仓库:扩展 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

771 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 飞牛 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`