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 体系完整
180 lines
4.3 KiB
Markdown
180 lines
4.3 KiB
Markdown
# 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. 首次准备
|
||
|
||
```bash
|
||
# [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. 基础设施启停
|
||
|
||
```bash
|
||
# [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. 应用启停
|
||
|
||
```bash
|
||
# [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 命令
|
||
|
||
```bash
|
||
# [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`，关键项：
|
||
|
||
```env
|
||
# 数据库
|
||
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. 部署备份
|
||
|
||
```bash
|
||
# [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 端。
|