QUICKSTART.md

海关数据系统 - 快速启动指南

前置要求

• Docker & Docker Compose
• Python 3.14+
• Git

1. 克隆项目

git clone <repository-url>
cd customs-data

2. 环境配置

# 复制环境变量模板
cp .env.template .env

# 编辑 .env，至少配置以下必需项：
# - DATABASE_URL
# - CLICKHOUSE_URL
# - ELASTICSEARCH_URL
# - REDIS_URL

可选配置（推荐）

# 配置至少一个告警渠道
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx

# 配置邮件通知（用于导出和订阅）
SENDGRID_API_KEY=SG.xxx
NOTIFICATION_FROM_EMAIL=noreply@customs-data.com

3. 启动依赖服务

# 启动 PostgreSQL、ClickHouse、Elasticsearch、Redis
docker compose up -d db clickhouse elasticsearch redis

# 等待服务就绪（约30秒）
docker compose ps

4. 初始化数据库

# 创建 Python 虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 初始化数据库表
python init_db.py

5. 启动服务

方式一：Docker Compose（推荐）

# 启动所有服务（API、Worker、Scheduler）
docker compose up -d

# 查看日志
docker compose logs -f api worker

方式二：本地开发模式

# 终端 1：启动 API 服务
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --reload

# 终端 2：启动 Celery Worker
celery -A packages.core.celery_app worker --loglevel=info

# 终端 3：启动 Celery Beat（定时任务）
celery -A packages.core.celery_app beat --loglevel=info

6. 验证服务

6.1 健康检查

# 基础健康检查
curl http://localhost:8000/api/v1/health/

# 完整健康检查（需要 API Key）
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/full

6.2 查看 API 文档

打开浏览器访问：http://localhost:8000/docs

7. 运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/baseline/test_api_contracts.py -v

8. 数据同步示例

同步巴西数据

# 手动触发巴西数据同步
python -m apps.worker.run_brazil

# 或通过 API 触发（需要 API Key）
curl -X POST -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/admin/sync/brazil

历史回补

# 回补巴西 2023 年数据
python apps/worker/run_backfill.py BR 2023-01-01 2023-12-31

9. API 使用示例

9.1 搜索贸易记录

curl -X POST http://localhost:8000/api/v1/trade/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev_key_12345" \
  -d '{
    "source_country": "BR",
    "product_name": "mobile phone",
    "start_date": "2024-01-01",
    "page": 1,
    "limit": 20
  }'

9.2 创建订阅

curl -X POST http://localhost:8000/api/v1/subscription/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev_key_12345" \
  -d '{
    "user_email": "user@example.com",
    "target_hs_code": "851712"
  }'

9.3 提交导出任务

curl -X POST http://localhost:8000/api/v1/export/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: paid_key_12345" \
  -d '{
    "country": "BR",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "email": "user@example.com"
  }'

9.4 查询任务状态

curl http://localhost:8000/api/v1/export/status/{task_id} \
  -H "X-API-Key: paid_key_12345"

10. 监控与告警

查看健康状态

# PostgreSQL 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/postgres

# ClickHouse 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/clickhouse

# Elasticsearch 健康检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/elasticsearch

# 数据一致性检查
curl -H "X-API-Key: dev_key_12345" \
  http://localhost:8000/api/v1/health/consistency

查看日志

# Docker 日志
docker compose logs -f api worker

# 本地日志文件
tail -f logs/app.log

11. 常见问题

Q: PostgreSQL 连接失败

# 检查服务状态
docker compose ps db

# 重启服务
docker compose restart db

Q: Elasticsearch 内存不足

# 增加 Elasticsearch 内存限制（docker-compose.yml）
environment:
  - "ES_JAVA_OPTS=-Xms512m -Xmx512m"

Q: Celery Worker 未启动

# 检查 Redis 连接
docker compose ps redis

# 查看 Worker 日志
docker compose logs worker

Q: 测试失败

# 确保测试数据库初始化
TEST_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5434/customs_data_test \
python init_db.py

# 重新运行测试
pytest tests/ -v --tb=short

12. 停止服务

# 停止所有服务
docker compose down

# 停止并删除数据卷（清空数据）
docker compose down -v

13. 下一步

• 查看 开发完成总结 了解系统功能
• 查看 项目现状与未完成项梳理 了解开发进度
• 查看 国家与数据源接入清单 了解数据覆盖
• 配置告警 Webhook 接收实时通知
• 配置 SendGrid 接收邮件通知
• 添加更多真实数据源连接器

14. 技术支持

• 文档：docs/ 目录
• 测试：tests/ 目录
• 示例：temporary/ 目录
• 问题反馈：提交 Issue

---

祝使用愉快！ 🎉