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. 克隆项目

git clone <repository-url>
cd CA

2. 配置环境变量

cp deploy/.env.example deploy/.env

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

# 数据库密码 (必须修改)
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. 启动服务

cd deploy
docker compose up -d

4. 验证部署

# 检查服务状态
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 中:

# 查看 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 表

docker compose exec postgres psql -U wuhan_user -d wuhan_disease -f /docker-entrypoint-initdb.d/init.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. 导入网格数据

# 从容器外复制数据到容器
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. 后端开发环境

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. 前端开发环境

cd frontend
npm install
npm run dev

3. 运行测试

# 后端测试
cd backend
pytest

# 前端测试
cd frontend
npm test

# E2E 测试
cd frontend
npx playwright test

---

生产环境部署

1. 安全配置

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

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

2. 性能优化

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

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

3. 日志管理

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

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

---

故障排查

常见问题

1. 后端无法连接数据库

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

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

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

2. 前端无法连接后端

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

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

3. 内存不足

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

---

备份与恢复

备份

# 数据库备份
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/

恢复

# 数据库恢复
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 指标 (未来扩展)

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

---

更新与升级

更新代码

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

数据库迁移

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

---

联系与支持

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