# 本地开发环境

本文说明 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 主密钥来“修复”单条凭据。