MomentumLab/app/backend/DOCKER_SYNC.md

# Docker 代码同步指南

本文档说明如何在代码更改后同步到 Docker 容器中。

## 🚀 三种同步方案

| 方案 | 适用场景 | 同步速度 | 特点 |
|------|---------|---------|------|
| **开发模式** | 日常开发 | 实时 | 热重载，自动同步 |
| **重建模式** | 生产部署 | 2-3分钟 | 全新镜像，干净环境 |
| **快速重启** | 配置更改 | 10秒 | 重启容器，保留数据 |

---

## 方案一：开发模式（推荐）

使用 Volume 挂载实现代码实时同步，支持热重载。

### 启动开发环境

```bash
cd app/backend

# Windows
-dev-start.bat

# Linux/Mac
./dev-start.sh
```

### 工作原理

```
宿主机                    Docker 容器
├─ src/        ────────►  /app/src/         (只读挂载)
├─ prisma/     ────────►  /app/prisma/     (只读挂载)
├─ package.json ───────►  /app/package.json (只读挂载)
└─ logs/       ◄────────  /app/logs/        (读写挂载)
```

### 特性

- ✅ **实时同步**：修改 `src/` 下的代码立即生效
- ✅ **热重载**：使用 `tsx watch` 自动重启服务
- ✅ **无需重建**：无需 `docker build`，秒级同步
- ✅ **调试友好**：支持 `console.log` 实时输出

### 常用命令

```bash
# 查看实时日志
docker-compose -f docker-compose.dev.yml logs -f app

# 重启应用服务
docker-compose -f docker-compose.dev.yml restart app

# 停止开发环境
docker-compose -f docker-compose.dev.yml stop

# 完全删除（包括数据）
docker-compose -f docker-compose.dev.yml down -v
```

### 文件变更自动同步

| 操作 | 效果 |
|------|------|
| 修改 `src/**/*.ts` | 服务自动重启，变更立即生效 |
| 修改 `prisma/schema.prisma` | 需要重启容器重新生成 Client |
| 修改 `package.json` | 需要重启容器重新安装依赖 |
| 修改 `.env` | 需要重启容器加载新配置 |

---

## 方案二：重建模式（生产部署）

代码更改后重新构建镜像，适合生产环境部署。

### 完整重建流程

```bash
cd app/backend

# 1. 停止现有服务
docker-compose down

# 2. 重新构建镜像（无缓存）
docker-compose build --no-cache

# 3. 启动服务
docker-compose up -d
```

### 快速重建（使用缓存）

```bash
# 一键重建并启动
docker-compose up --build -d

# 或
./docker-start.sh
```

### 仅更新应用代码

```bash
# 如果只有代码变更，可以快速重建
docker-compose build app --no-cache
docker-compose up -d
```

---

## 方案三：快速重启（配置更改）

仅重启容器，不重建镜像，保留所有数据。

```bash
# 重启所有服务
docker-compose restart

# 仅重启应用服务
docker-compose restart app

# 重启并查看日志
docker-compose restart app && docker-compose logs -f app
```

---

## 📋 不同场景的推荐方案

### 场景 1：修改业务逻辑代码

**推荐**：开发模式

```bash
# 启动开发环境
./dev-start.sh

# 修改 src/services/stockService.ts
# 保存后自动同步，无需其他操作
```

### 场景 2：修改数据库模型（Prisma Schema）

**推荐**：重建模式

```bash
# 1. 修改 prisma/schema.prisma

# 2. 重新构建并启动
docker-compose down
docker-compose up --build -d

# 3. 执行数据库迁移
docker-compose exec app npx prisma migrate dev
```

### 场景 3：添加新依赖（package.json）

**推荐**：重建模式

```bash
# 1. 修改 package.json，添加依赖

# 2. 重新构建
docker-compose down
docker-compose build app --no-cache
docker-compose up -d
```

### 场景 4：修改配置文件（.env）

**推荐**：快速重启

```bash
# 1. 修改 .env.docker

# 2. 重启服务
docker-compose restart app
```

### 场景 5：生产环境部署

**推荐**：生产模式

```bash
# 使用生产配置
docker-compose -f docker-compose.yml up --build -d

# 验证部署
node verify-docker.js
```

---

## 🔧 高级技巧

### 1. 进入容器内部调试

```bash
# 进入应用容器
docker-compose exec app sh

# 查看容器内的代码
ls -la /app/src/

# 手动运行命令
npx tsx src/app.ts
```

### 2. 查看容器内的日志文件

```bash
# 进入容器查看日志
docker-compose exec app sh -c "tail -f /app/logs/combined-*.log"
```

### 3. 强制刷新（清除缓存）

```bash
# 清除 Docker 构建缓存
docker builder prune -f

# 重新构建
docker-compose up --build -d
```

### 4. 同时运行开发和生产环境

```bash
# 终端 1：启动开发环境（端口 3000）
./dev-start.sh

# 终端 2：修改代码，实时查看效果
```

### 5. 数据库变更后同步

```bash
# 如果修改了数据库初始化脚本
docker-compose down -v  # 删除数据卷
docker-compose up -d     # 重新初始化
```

---

## 🐛 常见问题

### 问题 1：代码修改后没有生效

**原因**：可能是缓存或挂载问题

**解决**：
```bash
# 方案 A：重启应用服务
docker-compose -f docker-compose.dev.yml restart app

# 方案 B：强制重新创建容器
docker-compose -f docker-compose.dev.yml up -d --force-recreate app
```

### 问题 2：node_modules 不同步

**原因**：Volume 挂载覆盖了容器内的 node_modules

**解决**：
```bash
# 开发模式已使用命名卷隔离 node_modules，通常无需处理
# 如需重新安装依赖：
docker-compose -f docker-compose.dev.yml exec app npm install
```

### 问题 3：Prisma Client 未更新

**原因**：修改 schema 后需要重新生成 Client

**解决**：
```bash
# 进入容器重新生成
docker-compose -f docker-compose.dev.yml exec app npx prisma generate

# 或重启容器
docker-compose -f docker-compose.dev.yml restart app
```

### 问题 4：端口被占用

**原因**：其他服务占用了 3000/3306/6379 端口

**解决**：
```bash
# 查看占用进程
lsof -i :3000

# 或修改 docker-compose.dev.yml 的端口映射
ports:
  - "3001:3000"  # 改为 3001 端口
```

---

## 📝 最佳实践

### 开发流程

1. **日常开发**：使用开发模式
   ```bash
   ./dev-start.sh
   ```

2. **修改代码**：在宿主机编辑，容器内自动同步

3. **测试验证**：访问 http://localhost:3000

4. **提交代码**：正常 git 提交流程

5. **生产部署**：重建模式
   ```bash
   docker-compose up --build -d
   ```

### 文件修改 checklist

| 文件类型 | 同步方式 | 是否需要重建 |
|---------|---------|------------|
| `src/**/*.ts` | 自动同步 | ❌ 否 |
| `src/**/*.js` | 自动同步 | ❌ 否 |
| `prisma/schema.prisma` | 需重启 | ⚠️ 建议重建 |
| `package.json` | 需重启 | ✅ 需要重建 |
| `.env` | 需重启 | ⚠️ 重启即可 |
| `Dockerfile` | 需重建 | ✅ 需要重建 |
| `docker-compose.yml` | 需重建 | ✅ 需要重建 |

---

## 📚 相关文档

- [Docker 部署指南](./DOCKER_README.md)
- [开发启动脚本](./dev-start.sh)
- [生产启动脚本](./docker-start.sh)
- [部署验证脚本](./verify-docker.js)