selfrelease
51feae55ba
- 后端：FastAPI + SQLAlchemy + Alembic，7 张核心表迁移成功 - 前端：Next.js 16 + TailwindCSS 4 + 三端布局（投资人/创始人/Admin） - 数据库：PostgreSQL 16，7 张核心实体表（tenants/users/companies/monthly_reports/health_scores/risk_events/audit_logs） - Docker：docker-compose.yml + 前后端 Dockerfile - 测试：健康检查 4 个测试全部 GREEN - 文档：README/run.md/AGENTS.md/docs 体系完整
4.3 KiB
4.3 KiB
run.md — 运维手册
1. 技术栈
| 层 | 技术 | 版本 |
|---|---|---|
| 前端 | Next.js + React + TypeScript | 15.x / 19.x / 5.x |
| UI | TailwindCSS 4.x + shadcn/ui + lucide + recharts + sonner | — |
| 后端 | Python 3.12 + FastAPI 0.115.x | — |
| ORM | SQLAlchemy 2.x + Alembic | — |
| 数据库 | PostgreSQL 16 + PgVector | — |
| 缓存 | Redis 7.x | — |
| AI | Ollama（本地推理）+ LangChain | — |
| 包管理 | pnpm（前端）+ uv（后端） | — |
| 部署 | Docker Compose | — |
2. 首次准备
# [Native] 安装依赖
brew install pnpm uv docker ollama
# [Native] 拉取 AI 模型
ollama pull qwen2.5:7b
# [Docker] 启动基础设施
docker compose up -d postgres redis ollama
# [Native] 后端
cd backend
uv sync
cp ../.env.example ../.env
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8000
# [Native] 前端
cd frontend
pnpm install
pnpm dev
3. 基础设施启停
# [Docker] 启动
docker compose up -d postgres redis ollama
# [Docker] 停止
docker compose stop postgres redis ollama
# [Docker] 查看状态
docker compose ps
# [Docker] 查看日志
docker compose logs -f postgres
docker compose logs -f redis
4. 应用启停
# [Native] 后端启动
cd backend && uv run uvicorn app.main:app --reload --port 8000
# [Native] 后端停止
Ctrl+C
# [Native] 前端启动
cd frontend && pnpm dev
# [Native] 前端停止
Ctrl+C
# [Docker] 全部启动
docker compose up -d
# [Docker] 全部停止
docker compose down
5. DB 命令
# [Docker] 进入 psql
docker compose exec postgres psql -U postgres -d aiportpilot
# [Native] 创建迁移
cd backend && uv run alembic revision --autogenerate -m "description"
# [Native] 执行迁移
cd backend && uv run alembic upgrade head
# [Native] 回滚一个版本
cd backend && uv run alembic downgrade -1
# [Native] 查看当前版本
cd backend && uv run alembic current
# [Docker] 备份数据库
docker compose exec postgres pg_dump -U postgres aiportpilot > backup_$(date +%Y%m%d).sql
# ⚠️ [Docker] 恢复数据库（危险！会覆盖现有数据）
# docker compose exec -T postgres psql -U postgres -d aiportpilot < backup_20250718.sql
6. 排错
| 问题 | 排查 |
|---|---|
| 后端启动失败 | 检查 .env 配置、PostgreSQL 是否运行 |
| 前端 API 401 | 检查 token 是否过期、frontend/.env.local 的 API URL |
| AI 解析超时 | 检查 Ollama 是否运行、模型是否已拉取 |
| 数据库连接失败 | docker compose ps 检查 PostgreSQL 状态 |
| 迁移冲突 | alembic history 检查，手动解决后重新生成 |
7. 端口表
| 服务 | 端口 | 说明 |
|---|---|---|
| Next.js | 3000 | 前端 dev server |
| FastAPI | 8000 | 后端 API server |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 缓存 |
| Ollama | 11434 | 本地 AI 推理 |
8. 环境变量
见 .env.example，关键项：
# 数据库
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aiportpilot
# Redis
REDIS_URL=redis://localhost:6379/0
# JWT
JWT_SECRET_KEY=change-me-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_TTL_MINUTES=120
JWT_REFRESH_TOKEN_TTL_DAYS=7
# AI
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
# 前端
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
9. 部署备份
# [Docker] 全量备份（数据库 + 文件）
docker compose exec postgres pg_dump -U postgres aiportpilot > backups/db_$(date +%Y%m%d_%H%M).sql
# [Native] 代码备份（Git）
git tag backup-$(date +%Y%m%d)
git push origin --tags
# ⚠️ [Docker] 恢复（危险！先停止应用）
# docker compose stop backend frontend
# docker compose exec -T postgres psql -U postgres -d aiportpilot < backups/db_20250718.sql
# docker compose start backend frontend
10. FAQ
Q: 如何切换 AI 模型？
A: 修改 .env 中 OLLAMA_MODEL，然后 ollama pull <model_name>。
Q: 如何添加新企业行业选项？
A: 修改 backend/app/core/enums.py 中的 Industry 枚举，执行迁移。
Q: 如何调整健康度权重？
A: 修改 backend/app/services/health_calculator.py 中的权重配置。
Q: 前端如何切换投资人/创始人端？
A: 路由组自动隔离：/ → 投资人端，/founder → 创始人端，/admin → Admin 端。