335 lines
7.7 KiB
Markdown
335 lines
7.7 KiB
Markdown
# 本地开发环境
|
||
|
||
本文说明 Windows 和 Linux/macOS 上的本地配置、三种启动方式、数据库初始化、质量检查及
|
||
常见问题。生产环境请使用[生产部署与恢复手册](../operations/production-runbook.md)。
|
||
|
||
## 1. 前置环境
|
||
|
||
- Python 3.12
|
||
- Node.js 22 或更高版本
|
||
- pnpm 11.9.0
|
||
- Docker Desktop，或 Docker Engine + Compose
|
||
- Git
|
||
|
||
建议通过 Corepack 启用仓库声明的 pnpm：
|
||
|
||
```bash
|
||
corepack enable
|
||
corepack prepare pnpm@11.9.0 --activate
|
||
```
|
||
|
||
检查版本：
|
||
|
||
```bash
|
||
python --version
|
||
node --version
|
||
pnpm --version
|
||
docker compose version
|
||
```
|
||
|
||
## 2. 初始化配置
|
||
|
||
在项目根目录复制环境变量模板：
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
Linux/macOS：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
生成稳定的 Fernet 主密钥：
|
||
|
||
```bash
|
||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||
```
|
||
|
||
把结果写入 `.env` 的 `AI_CREDENTIAL_ENCRYPTION_KEY`。已经保存模型、MCP、渠道或 OIDC
|
||
凭据后不要直接更换主密钥，否则历史密文将无法解密。
|
||
|
||
本地至少检查：
|
||
|
||
- `DJANGO_SECRET_KEY`
|
||
- `DJANGO_SUPERUSER_PASSWORD`
|
||
- `POSTGRES_PASSWORD`
|
||
- `MINIO_ROOT_USER`、`MINIO_ROOT_PASSWORD`
|
||
- `MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY`
|
||
- `AI_CREDENTIAL_ENCRYPTION_KEY`
|
||
- `INTERNAL_MCP_TOKEN`
|
||
- `METRICS_TOKEN`
|
||
|
||
`.env` 已被 Git 忽略，不得把真实值写回 `.env.example`。
|
||
|
||
## 3. 启动方式
|
||
|
||
### 3.1 完整 Docker 环境
|
||
|
||
适合第一次启动和端到端联调：
|
||
|
||
```powershell
|
||
docker compose -f infra/docker-compose.yml --env-file .env up --build
|
||
```
|
||
|
||
包含 PostgreSQL、Redis、MinIO、ClamAV、Django、Celery Worker、Celery Beat 和 React。
|
||
后端入口会等待依赖服务、执行数据库迁移并初始化治理数据。
|
||
|
||
访问地址：
|
||
|
||
- 前端：<http://localhost:5173>
|
||
- API 文档：<http://localhost:8000/api/docs>
|
||
- 存活探针：<http://localhost:8000/api/system/health/live>
|
||
- 就绪探针：<http://localhost:8000/api/system/health/ready>
|
||
- MinIO 控制台：<http://localhost:9001>
|
||
|
||
停止环境：
|
||
|
||
```powershell
|
||
docker compose -f infra/docker-compose.yml --env-file .env down
|
||
```
|
||
|
||
不要随意添加 `-v`，该参数会删除本地数据库和对象存储卷。
|
||
|
||
### 3.2 Docker 基础设施 + 宿主机应用
|
||
|
||
适合频繁调试后端和前端：
|
||
|
||
```powershell
|
||
docker compose -f infra/docker-compose.local.yml --env-file .env up -d
|
||
```
|
||
|
||
宿主机进程需要把容器服务名覆盖为本机地址：
|
||
|
||
```env
|
||
POSTGRES_HOST=localhost
|
||
CELERY_BROKER_URL=redis://localhost:6379/0
|
||
CELERY_RESULT_BACKEND=redis://localhost:6379/1
|
||
MINIO_ENDPOINT=localhost:9000
|
||
CLAMAV_HOST=localhost
|
||
API_PROXY_TARGET=http://localhost:8000
|
||
```
|
||
|
||
安装并启动后端：
|
||
|
||
```powershell
|
||
cd backend
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m pip install -e ".[dev]"
|
||
python manage.py migrate
|
||
python manage.py bootstrap_governance
|
||
python manage.py runserver 0.0.0.0:8000
|
||
```
|
||
|
||
Linux/macOS 激活虚拟环境：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
另开终端启动异步进程：
|
||
|
||
```powershell
|
||
cd backend
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m celery -A config.celery worker -l info -P solo
|
||
```
|
||
|
||
```powershell
|
||
cd backend
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m celery -A config.celery beat -l info
|
||
```
|
||
|
||
安装并启动前端：
|
||
|
||
```powershell
|
||
cd frontend
|
||
pnpm install --frozen-lockfile
|
||
pnpm dev
|
||
```
|
||
|
||
前端通过同源 `/api` 代理后端，局域网访问时无需把浏览器 API 地址写成
|
||
`localhost:8000`。
|
||
|
||
### 3.3 Windows 后端辅助脚本
|
||
|
||
基础设施已启动时，可在项目根目录执行：
|
||
|
||
```powershell
|
||
.\start-backend.ps1
|
||
```
|
||
|
||
脚本校验 `.env` 和 Fernet 主密钥，分别启动 Django、Celery Worker 和 Celery Beat。
|
||
它不会启动 Docker、前端或执行迁移。修改 `.env` 后使用：
|
||
|
||
```powershell
|
||
.\start-backend.ps1 -Restart
|
||
```
|
||
|
||
## 4. 数据库与初始数据
|
||
|
||
创建或更新迁移：
|
||
|
||
```powershell
|
||
cd backend
|
||
python manage.py makemigrations
|
||
python manage.py migrate
|
||
python manage.py bootstrap_governance
|
||
```
|
||
|
||
提交前必须确认没有遗漏迁移：
|
||
|
||
```powershell
|
||
python manage.py makemigrations --check --dry-run
|
||
```
|
||
|
||
开发环境默认管理员为 `admin / admin12345`，可通过 `.env` 中的
|
||
`DJANGO_SUPERUSER_*` 修改。生产环境禁止使用默认密码。
|
||
|
||
## 5. AI 能力初始化
|
||
|
||
### 5.1 模型、Skill 和 Agent
|
||
|
||
1. 使用管理员进入 `#/modelhub/providers`，创建 OpenAI-compatible 渠道和模型部署。
|
||
2. 文本步骤使用 `text_chat`；包含图片时使用 `vision_chat`，并单独批准图片出境。
|
||
3. 在 `#/skills` 管理 Skill 草稿和发布版本。
|
||
4. 在 `#/agents` 配置步骤、模型、输入映射和授权动作。
|
||
5. 在 `#/agent-runs` 查看冻结配置、步骤轨迹、调用尝试、Token 和耗时。
|
||
|
||
发布可信建单 Agent：
|
||
|
||
```powershell
|
||
cd backend
|
||
python manage.py publish_trusted_ticket_intake --deployment-id 1
|
||
```
|
||
|
||
发布支持分析 Agent：
|
||
|
||
```powershell
|
||
python manage.py publish_support_analysis --deployment-id 1
|
||
```
|
||
|
||
发布知识蒸馏 Agent：
|
||
|
||
```powershell
|
||
python manage.py publish_knowledge_distillation --deployment-id 1
|
||
```
|
||
|
||
### 5.2 混合检索
|
||
|
||
在模型中心创建 `embedding` 部署，可选创建 `rerank` 部署，并配置：
|
||
|
||
```env
|
||
KNOWLEDGE_EMBEDDING_DEPLOYMENT_ID=<Embedding 部署 ID>
|
||
KNOWLEDGE_EMBEDDING_DIMENSIONS=1536
|
||
KNOWLEDGE_EMBEDDING_ALLOW_HASH_FALLBACK=false
|
||
KNOWLEDGE_RERANK_DEPLOYMENT_ID=<可选重排部署 ID>
|
||
```
|
||
|
||
维度变更必须同时提供数据库迁移。重建现有索引：
|
||
|
||
```powershell
|
||
python manage.py rebuild_knowledge_embeddings
|
||
```
|
||
|
||
生产环境使用 PostgreSQL 全文和 pgvector HNSW。哈希向量回退只允许测试或明确的本地开发。
|
||
|
||
### 5.3 自动解决
|
||
|
||
自动解决默认关闭。启用前需要同时满足：
|
||
|
||
- Agent 发布版本包含自动解决授权。
|
||
- 发起人具有 `ticket.resolve` 权限。
|
||
- 结果通过引用、风险和置信度校验。
|
||
- `TICKET_AUTO_RESOLVE_ENABLED=true`。
|
||
- 匹配分数达到 `TICKET_AUTO_RESOLVE_MIN_SCORE`。
|
||
|
||
## 6. 质量检查
|
||
|
||
后端：
|
||
|
||
```powershell
|
||
cd backend
|
||
pytest
|
||
ruff check .
|
||
python manage.py check
|
||
python manage.py makemigrations --check --dry-run
|
||
```
|
||
|
||
前端：
|
||
|
||
```powershell
|
||
cd frontend
|
||
pnpm install --frozen-lockfile
|
||
pnpm test:run
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
当前完整基线为后端 217 项、前端 73 项。更详细的测试分层和提交规范见
|
||
[开发指南](development-guide.md)。
|
||
|
||
## 7. 固定验收入口
|
||
|
||
- 智能建单真实文本闭环：
|
||
|
||
```powershell
|
||
python manage.py verify_ticket_intake --username admin
|
||
```
|
||
|
||
- 阶段 2 报告：
|
||
|
||
```powershell
|
||
python manage.py report_stage2_acceptance
|
||
```
|
||
|
||
- 阶段 3 报告：
|
||
|
||
```powershell
|
||
python manage.py report_stage3_acceptance
|
||
```
|
||
|
||
- 统一蓝图报告：
|
||
|
||
```powershell
|
||
python manage.py report_blueprint_readiness `
|
||
--evidence ../docs/product/acceptance/blueprint-external-evidence.template.json
|
||
```
|
||
|
||
合成案例只能用于开发回归，不得替代真实业务验收。
|
||
|
||
## 8. 常见问题
|
||
|
||
### 前端提示 esbuild 构建被忽略
|
||
|
||
确认使用 pnpm 11.9.0，并检查 `pnpm-workspace.yaml` 中 `allowBuilds.esbuild` 为 `true`，
|
||
然后重新执行 `pnpm install --frozen-lockfile`。
|
||
|
||
### 材料上传后扫描失败
|
||
|
||
确认 ClamAV 已健康：
|
||
|
||
```powershell
|
||
docker compose -f infra/docker-compose.local.yml ps clamav
|
||
```
|
||
|
||
ClamAV 首次启动需要下载病毒库。扫描失败只影响对应材料，原件会保留。
|
||
|
||
### MinIO 附件不可用
|
||
|
||
宿主机运行后端时确认 `MINIO_ENDPOINT=localhost:9000`；容器内后端应使用
|
||
`MINIO_ENDPOINT=minio:9000`。
|
||
|
||
### Agent 一直处于 queued
|
||
|
||
检查 Redis、Celery Worker 和 Beat 是否运行，并确认 Django 与 Celery 使用同一份 `.env`
|
||
和 `AI_CREDENTIAL_ENCRYPTION_KEY`。
|
||
|
||
### 修改模型凭据后 Celery 仍报解密失败
|
||
|
||
重启 Django 和所有 Celery 进程。禁止通过替换 Fernet 主密钥来“修复”单条凭据。
|