# 部署文档

## 环境要求

- Docker >= 20.x
- Docker Compose >= 2.x
- 服务器开放 80 端口

---

## 快速部署

### 1. 上传代码

将整个项目目录上传到服务器（或通过 git clone）：

```bash
git clone <your-repo-url> geo2
cd geo2
```

### 2. 配置环境变量

在项目根目录创建 `.env.prod` 文件：

```bash
POSTGRES_PASSWORD=your-strong-password
CRYPTO_KEY=your-32-character-secret-key!!
ANALYSIS_CONCURRENCY=3
```

> **注意**：`CRYPTO_KEY` 必须恰好 32 个字符，用于 AES-256 加密。

### 3. 启动服务

```bash
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build
```

### 4. 验证运行状态

```bash
docker compose -f docker-compose.prod.yml ps
```

所有服务状态应为 `running`：

```
NAME         STATUS
postgres     running
redis        running
backend      running
frontend     running
```

### 5. 访问应用

浏览器打开：`http://<服务器IP>`

---

## 服务架构

```
用户浏览器
    │
    ▼ :80
[ frontend (nginx) ]
    │ /api/* → proxy
    ▼ :3000
[ backend (NestJS) ]
    ├── PostgreSQL :5432
    └── Redis      :6379
```

| 服务       | 镜像基础          | 对外端口 | 说明               |
|------------|-------------------|----------|--------------------|
| frontend   | nginx:alpine      | 80       | React 静态文件     |
| backend    | node:20-alpine    | 内网     | NestJS API 服务    |
| postgres   | postgres:15-alpine| 内网     | 主数据库           |
| redis      | redis:7-alpine    | 内网     | 任务队列缓存       |

---

## 常用运维命令

### 查看日志

```bash
# 所有服务
docker compose -f docker-compose.prod.yml logs -f

# 单个服务
docker compose -f docker-compose.prod.yml logs -f backend
```

### 重启服务

```bash
docker compose -f docker-compose.prod.yml restart backend
```

### 停止所有服务

```bash
docker compose -f docker-compose.prod.yml down
```

### 停止并清除数据库数据

```bash
docker compose -f docker-compose.prod.yml down -v
```

> **警告**：`-v` 会删除 PostgreSQL 数据卷，数据不可恢复。

### 更新部署（拉取新代码后）

```bash
git pull
docker compose -f docker-compose.prod.yml up -d --build
```

---

## 数据库备份与恢复

### 备份

```bash
docker compose -f docker-compose.prod.yml exec postgres \
  pg_dump -U geo geo > backup_$(date +%Y%m%d).sql
```

### 恢复

```bash
cat backup_20260101.sql | docker compose -f docker-compose.prod.yml exec -T postgres \
  psql -U geo geo
```

---

## 故障排查

### 后端无法连接数据库

检查 postgres 是否已就绪：

```bash
docker compose -f docker-compose.prod.yml logs postgres
```

postgres 容器需要看到 `database system is ready to accept connections` 后 backend 才能正常启动。

### 前端页面空白

检查 nginx 是否正常：

```bash
docker compose -f docker-compose.prod.yml logs frontend
```

### API 请求报 502

后端可能未启动完成，等待约 10 秒后刷新，或查看：

```bash
docker compose -f docker-compose.prod.yml logs backend
```

---

## 安全建议

- 修改 `POSTGRES_PASSWORD` 为强密码（16位以上，含大小写+数字+符号）
- 修改 `CRYPTO_KEY` 为随机32字符字符串
- 服务器防火墙只开放 80（或443）端口，数据库和 Redis 不对外暴露
- 生产环境建议在 nginx 前配置 HTTPS（使用 Let's Encrypt 或反向代理）