Files

T

selfrelease 51feae55ba feat(backend): Phase 0 项目骨架完成 — 后端/前端/数据库/Docker

- 后端：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 体系完整

2026-07-18 21:50:15 +08:00

4.3 KiB

Raw Blame History

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 端。

4.3 KiB Raw Blame History Unescape Escape