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