CA/docs/DEPLOYMENT.md

# 武汉市疾病监测预警系统 - 部署文档

## 系统要求

### 硬件要求
- **CPU**: 4 核以上
- **内存**: 8GB 以上 (推荐 16GB)
- **存储**: 50GB 可用空间
- **网络**: 本地部署无需公网

### 软件要求
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **PostgreSQL**: 15+ (通过 Docker 提供)
- **Node.js**: 18+ (仅开发环境)
- **Python**: 3.11+ (仅开发环境)

---

## 快速开始 (Docker Compose)

### 1. 克隆项目

```bash
git clone <repository-url>
cd CA
```

### 2. 配置环境变量

```bash
cp deploy/.env.example deploy/.env
```

编辑 `deploy/.env` 文件，修改以下关键配置:

```bash
# 数据库密码 (必须修改)
POSTGRES_PASSWORD=your_secure_password

# 数据库连接字符串 (必须与密码一致)
DATABASE_URL=postgresql://wuhan_user:your_secure_password@postgres:5432/wuhan_disease

# API 地址 (开发环境)
VITE_API_URL=http://localhost:8000
```

### 3. 启动服务

```bash
cd deploy
docker compose up -d
```

### 4. 验证部署

```bash
# 检查服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 测试后端 API
curl http://localhost:8000/health

# 测试前端
curl http://localhost:3000
```

### 5. 访问应用

- **前端**: http://localhost:3000
- **后端 API**: http://localhost:8000
- **API 文档**: http://localhost:8000/docs
- **PostgreSQL**: localhost:5432

---

## 服务架构

```
┌─────────────────┐
│   Frontend      │  Port 3000
│   (Nginx)       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Backend      │  Port 8000
│   (FastAPI)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   PostgreSQL    │  Port 5432
│   (PostGIS)     │
└─────────────────┘
```

---

## Docker Compose 配置说明

### 服务列表

| 服务 | 镜像 | 端口 | 说明 |
|------|------|------|------|
| `postgres` | `postgis/postgis:15-3.3` | 5432 | PostgreSQL + PostGIS |
| `backend` | 本地构建 | 8000 | FastAPI 后端 |
| `frontend` | 本地构建 | 3000:80 | Nginx 前端 |

### 数据持久化

PostgreSQL 数据存储在 Docker volume `postgres_data` 中:

```bash
# 查看 volume
docker volume ls | grep postgres

# 备份数据
docker run --rm -v ca_deploy_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .

# 恢复数据
docker run --rm -v ca_deploy_postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /data
```

---

## 初始化数据库

### 1. 创建 grids 表

```bash
docker compose exec postgres psql -U wuhan_user -d wuhan_disease -f /docker-entrypoint-initdb.d/init.sql
```

或手动执行:

```sql
CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE IF NOT EXISTS grids (
    grid_id VARCHAR(20) PRIMARY KEY,
    geometry GEOMETRY(POLYGON, 4326) NOT NULL,
    center_lat DOUBLE PRECISION NOT NULL,
    center_lon DOUBLE PRECISION NOT NULL,
    district VARCHAR(50),
    dem DOUBLE PRECISION,
    population_density DOUBLE PRECISION,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_grids_geometry ON grids USING GIST (geometry);
CREATE INDEX idx_grids_district ON grids (district);
```

### 2. 导入网格数据

```bash
# 从容器外复制数据到容器
docker cp processed/grid_100m_index.parquet $(docker compose ps -q postgres):/tmp/grid_data.parquet

# 在容器内导入
docker compose exec postgres python3 << 'EOF'
import pandas as pd
import geopandas as gpd
from sqlalchemy import create_engine

df = pd.read_parquet('/tmp/grid_data.parquet')
gdf = gpd.GeoDataFrame(
    df,
    geometry=gpd.points_from_xy(df['center_lon'], df['center_lat']),
    crs='EPSG:4326'
)

engine = create_engine('postgresql://wuhan_user:wuhan_password@localhost:5432/wuhan_disease')
gdf.to_postgis('grids', engine, if_exists='replace', index=False)
EOF
```

---

## 开发环境部署

### 1. 后端开发环境

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 2. 前端开发环境

```bash
cd frontend
npm install
npm run dev
```

### 3. 运行测试

```bash
# 后端测试
cd backend
pytest

# 前端测试
cd frontend
npm test

# E2E 测试
cd frontend
npx playwright test
```

---

## 生产环境部署

### 1. 安全配置

```bash
# .env 文件
POSTGRES_PASSWORD=<强密码>
DATABASE_URL=postgresql://wuhan_user:<强密码>@postgres:5432/wuhan_disease

# 启用 HTTPS (通过反向代理)
# 配置 Nginx SSL 证书
```

### 2. 性能优化

```bash
# 增加 PostgreSQL 连接池
# 编辑 postgresql.conf
max_connections = 200
shared_buffers = 2GB

# 启用后端缓存
# 编辑 backend/app/performance.py
FEATURE_CACHE_TTL=7200  # 2 小时
```

### 3. 日志管理

```bash
# 查看实时日志
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres

# 导出日志
docker compose logs > all-logs.txt
```

---

## 故障排查

### 常见问题

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

```bash
# 检查数据库服务
docker compose ps postgres

# 查看数据库日志
docker compose logs postgres

# 测试连接
docker compose exec backend python -c "import asyncpg; asyncio.run(asyncpg.connect('postgresql://...'))"
```

#### 2. 前端无法连接后端

```bash
# 检查 VITE_API_URL 配置
docker compose exec frontend env | grep VITE

# 测试后端可达性
docker compose exec frontend curl http://backend:8000/health
```

#### 3. 内存不足

```bash
# 限制容器内存
# 编辑 docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 2G
```

---

## 备份与恢复

### 备份

```bash
# 数据库备份
docker compose exec postgres pg_dump -U wuhan_user wuhan_disease > backup.sql

# 完整备份 (数据库 + 配置文件)
tar czf backup-$(date +%Y%m%d).tar.gz \
  deploy/.env \
  backup.sql \
  processed/
```

### 恢复

```bash
# 数据库恢复
docker compose exec -T postgres psql -U wuhan_user -d wuhan_disease < backup.sql

# 解压备份
tar xzf backup-20260502.tar.gz
```

---

## 监控与告警

### 健康检查端点

- **后端**: `GET http://localhost:8000/health`
- **前端**: `GET http://localhost:3000`
- **数据库**: `docker compose exec postgres pg_isready`

### Prometheus 指标 (未来扩展)

```bash
# 启用指标端点
# 编辑 backend/main.py
from prometheus_fastapi_instrumentator import Instrumentator
Instrumentator().instrument(app).expose(app)
```

---

## 更新与升级

### 更新代码

```bash
git pull
docker compose down
docker compose build
docker compose up -d
```

### 数据库迁移

```bash
# 运行迁移脚本
docker compose exec backend python scripts/migrate.py
```

---

## 联系与支持

- **项目仓库**: `<repository-url>`
- **问题反馈**: GitHub Issues
- **文档**: `/docs` 目录