dysync/docs/部署指南.md

# dysync.net 部署指南

本文档详细说明如何将修改后的项目部署到生产环境。

## 📋 目录

1. [准备工作](#准备工作)
2. [构建 Docker 镜像](#构建-docker-镜像)
3. [推送到镜像仓库](#推送到镜像仓库)
4. [使用 Docker Compose 部署](#使用-docker-compose-部署)
5. [验证部署](#验证部署)
6. [常见问题](#常见问题)

---

## 🔧 准备工作

### 1. 环境要求

- **Docker**：版本 20.10+
- **Docker Compose**：版本 1.29+（或 Docker Compose V2）
- **.NET SDK 6.0**：用于构建项目（本地开发环境）
- **Node.js 18+**：用于构建前端（本地开发环境）
- **阿里云容器镜像服务账号**：用于推送镜像（或其他镜像仓库）

### 2. 创建必要的目录

```bash
# 在项目根目录创建以下目录（如果不存在）
mkdir -p db collect favorite uper logs
```

### 3. 配置镜像仓库（阿里云）

1. 登录 [阿里云容器镜像服务](https://cr.console.aliyun.com/)
2. 创建命名空间（如：`jianzhichu`）
3. 创建镜像仓库（如：`dysync.net`）
4. 获取登录凭证

---

## 🏗️ 构建 Docker 镜像

### 方式一：使用多阶段构建（推荐）

项目已提供优化的 `Dockerfile.prod`，包含前端和后端的完整构建：

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

### 方式二：手动构建前端后构建镜像

如果多阶段构建遇到问题，可以手动构建前端：

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

# 2. 确保 app/dist 目录存在且包含构建产物

# 3. 使用原始 Dockerfile 构建
docker build -t dysync.net:latest .
```

### 构建 ARM 架构镜像（适用于 Apple Silicon、树莓派等）

```bash
# 使用 Dockerfile-arm（如果存在）
docker build -f Dockerfile-arm -t dysync.net:arm-latest .

# 或者使用 buildx 构建多架构镜像
docker buildx build --platform linux/amd64,linux/arm64 -t dysync.net:latest .
```

---

## 📤 推送到镜像仓库

### 1. 登录阿里云容器镜像服务

```bash
# 替换为你的实际信息
docker login --username=你的用户名 registry.cn-hangzhou.aliyuncs.com
# 输入密码（在阿里云控制台获取）
```

### 2. 标记镜像

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

### 3. 推送镜像

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

---

## 🚀 使用 Docker Compose 部署

### 1. 准备 docker-compose.yml

项目根目录已包含 `docker-compose.yml` 文件，根据实际情况修改路径：

```yaml
version: '3.8'

services:
  dysync:
    image: registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest
    container_name: dysync
    restart: always
    ports:
      - "10101:10101"
    volumes:
      - ./db:/app/db              # 数据库目录
      - ./collect:/app/collect    # 收藏视频目录
      - ./favorite:/app/favorite  # 喜欢视频目录
      - ./uper:/app/uper          # 博主视频目录（可选）
      - ./logs:/app/logs          # 日志目录（可选）
    environment:
      - TZ=Asia/Shanghai
    dns:
      - 8.8.8.8
      - 114.114.114.114
```

### 2. 修改路径映射

**重要**：根据你的实际存储路径修改 `volumes` 部分：

```yaml
volumes:
  # Linux/Unix 路径示例
  - /volume1/docker/dysync/db:/app/db
  - /volume2/media/dysync/collect:/app/collect
  - /volume2/media/dysync/favorite:/app/favorite
  
  # Windows 路径示例（使用正斜杠）
  - D:/dysync/db:/app/db
  - D:/dysync/collect:/app/collect
  - D:/dysync/favorite:/app/favorite
  
  # macOS 路径示例
  - ~/dysync/db:/app/db
  - ~/dysync/collect:/app/collect
  - ~/dysync/favorite:/app/favorite
```

### 3. 启动服务

```bash
# 启动服务（后台运行）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 查看服务状态
docker-compose ps
```

### 4. 停止服务

```bash
# 停止服务
docker-compose down

# 停止并删除数据卷（谨慎使用，会删除数据）
docker-compose down -v
```

---

## ✅ 验证部署

### 1. 检查容器状态

```bash
docker ps | grep dysync
```

应该看到容器正在运行。

### 2. 检查日志

```bash
docker logs dysync
# 或
docker-compose logs -f dysync
```

应该看到类似输出：
```
dy.net service started successfully
Now listening on: http://[::]:10101
```

### 3. 访问应用

打开浏览器访问：
- **前端界面**：`http://你的服务器IP:10101`
- **Swagger API**：`http://你的服务器IP:10101/swagger`（如果启用）

### 4. 测试功能

1. 使用默认账号登录：`douyin` / `douyin2025`
2. 配置抖音 Cookie 和路径
3. 测试视频同步功能

---

## 🔄 更新部署

### 更新镜像并重启

```bash
# 1. 拉取最新镜像
docker-compose pull

# 2. 重启服务（会使用新镜像）
docker-compose up -d

# 3. 查看更新后的日志
docker-compose logs -f
```

### 重新构建并部署

```bash
# 1. 构建新镜像
docker build -f Dockerfile.prod -t dysync.net:latest .

# 2. 标记并推送
docker tag dysync.net:latest registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest
docker push registry.cn-hangzhou.aliyuncs.com/jianzhichu/dysync.net:latest

# 3. 在服务器上拉取并重启
docker-compose pull
docker-compose up -d
```

---

## 🐛 常见问题

### 1. 镜像构建失败

**问题：前端构建失败**
```bash
# 检查 Node.js 版本
node --version  # 应该是 18+

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

**问题：后端构建失败**
```bash
# 检查 .NET SDK 版本
dotnet --version  # 应该是 6.0.x

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

### 2. 容器启动失败

**问题：端口被占用**
```bash
# 检查端口占用
lsof -i :10101  # Linux/macOS
netstat -ano | findstr :10101  # Windows

# 修改 docker-compose.yml 中的端口映射
ports:
  - "10102:10101"  # 使用其他端口
```

**问题：权限错误**
```bash
# 确保目录有写权限
chmod -R 755 db collect favorite uper logs

# 或者使用 sudo（不推荐）
sudo docker-compose up -d
```

### 3. 数据丢失问题

**问题：容器删除后数据丢失**
- 确保 `volumes` 配置正确
- 使用绝对路径而不是相对路径
- 定期备份 `db` 目录

### 4. 网络问题

**问题：无法访问外网**
- 检查 DNS 配置
- 检查防火墙设置
- 使用 `network_mode: bridge` 或 `host`

### 5. 镜像拉取失败

**问题：认证失败**
```bash
# 重新登录
docker logout registry.cn-hangzhou.aliyuncs.com
docker login registry.cn-hangzhou.aliyuncs.com
```

**问题：网络超时**
```bash
# 使用国内镜像加速器
# 在 /etc/docker/daemon.json 添加：
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
```

---

## 📝 部署检查清单

- [ ] Docker 和 Docker Compose 已安装
- [ ] 创建了必要的目录（db, collect, favorite 等）
- [ ] 修改了 docker-compose.yml 中的路径映射
- [ ] 构建了 Docker 镜像（或使用现有镜像）
- [ ] 推送到镜像仓库（或使用本地镜像）
- [ ] 启动了 Docker Compose 服务
- [ ] 验证了容器正常运行
- [ ] 能够访问前端界面
- [ ] 能够登录系统
- [ ] 配置了抖音 Cookie 和路径
- [ ] 测试了视频同步功能

---

## 🔐 安全建议

1. **修改默认密码**：首次登录后立即修改默认密码
2. **使用 HTTPS**：生产环境建议配置反向代理（Nginx）并启用 HTTPS
3. **防火墙配置**：只开放必要的端口（10101）
4. **定期备份**：定期备份 `db` 目录和重要数据
5. **更新镜像**：定期更新镜像以获取安全补丁

---

## 📚 相关文档

- [本地启动指南](./本地启动指南.md)
- [视频预览功能说明](./视频预览功能说明.md)
- [README.md](./README.md)

---

**最后更新**：2024-11-22  
**版本**：v1.0