HaiLin/ai-ticket-platform

Fork 0

Files

hailin 78a70ee7c2 docs: complete Chinese project documentation

2026-07-27 19:08:08 +08:00

7.7 KiB

Raw Blame History

本地开发环境

本文说明 Windows 和 Linux/macOS 上的本地配置、三种启动方式、数据库初始化、质量检查及常见问题。生产环境请使用生产部署与恢复手册。

1. 前置环境

Python 3.12
Node.js 22 或更高版本
pnpm 11.9.0
Docker Desktop，或 Docker Engine + Compose
Git

建议通过 Corepack 启用仓库声明的 pnpm：

corepack enable
corepack prepare pnpm@11.9.0 --activate

检查版本：

python --version
node --version
pnpm --version
docker compose version

2. 初始化配置

在项目根目录复制环境变量模板：

Copy-Item .env.example .env

Linux/macOS：

cp .env.example .env

生成稳定的 Fernet 主密钥：

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 环境

适合第一次启动和端到端联调：

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

停止环境：

docker compose -f infra/docker-compose.yml --env-file .env down

不要随意添加 -v，该参数会删除本地数据库和对象存储卷。

3.2 Docker 基础设施 + 宿主机应用

适合频繁调试后端和前端：

docker compose -f infra/docker-compose.local.yml --env-file .env up -d

宿主机进程需要把容器服务名覆盖为本机地址：

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

安装并启动后端：

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 激活虚拟环境：

source .venv/bin/activate

另开终端启动异步进程：

cd backend
.\.venv\Scripts\Activate.ps1
python -m celery -A config.celery worker -l info -P solo

cd backend
.\.venv\Scripts\Activate.ps1
python -m celery -A config.celery beat -l info

安装并启动前端：

cd frontend
pnpm install --frozen-lockfile
pnpm dev

前端通过同源 /api 代理后端，局域网访问时无需把浏览器 API 地址写成 localhost:8000。

3.3 Windows 后端辅助脚本

基础设施已启动时，可在项目根目录执行：

.\start-backend.ps1

脚本校验 .env 和 Fernet 主密钥，分别启动 Django、Celery Worker 和 Celery Beat。它不会启动 Docker、前端或执行迁移。修改 .env 后使用：

.\start-backend.ps1 -Restart

4. 数据库与初始数据

创建或更新迁移：

cd backend
python manage.py makemigrations
python manage.py migrate
python manage.py bootstrap_governance

提交前必须确认没有遗漏迁移：

python manage.py makemigrations --check --dry-run

开发环境默认管理员为 admin / admin12345，可通过 .env 中的 DJANGO_SUPERUSER_* 修改。生产环境禁止使用默认密码。

5. AI 能力初始化

5.1 模型、Skill 和 Agent

使用管理员进入 #/modelhub/providers，创建 OpenAI-compatible 渠道和模型部署。
文本步骤使用 text_chat；包含图片时使用 vision_chat，并单独批准图片出境。
在 #/skills 管理 Skill 草稿和发布版本。
在 #/agents 配置步骤、模型、输入映射和授权动作。
在 #/agent-runs 查看冻结配置、步骤轨迹、调用尝试、Token 和耗时。

发布可信建单 Agent：

cd backend
python manage.py publish_trusted_ticket_intake --deployment-id 1

发布支持分析 Agent：

python manage.py publish_support_analysis --deployment-id 1

发布知识蒸馏 Agent：

python manage.py publish_knowledge_distillation --deployment-id 1

5.2 混合检索

在模型中心创建 embedding 部署，可选创建 rerank 部署，并配置：

KNOWLEDGE_EMBEDDING_DEPLOYMENT_ID=<Embedding 部署 ID>
KNOWLEDGE_EMBEDDING_DIMENSIONS=1536
KNOWLEDGE_EMBEDDING_ALLOW_HASH_FALLBACK=false
KNOWLEDGE_RERANK_DEPLOYMENT_ID=<可选重排部署 ID>

维度变更必须同时提供数据库迁移。重建现有索引：

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. 质量检查

后端：

cd backend
pytest
ruff check .
python manage.py check
python manage.py makemigrations --check --dry-run

前端：

cd frontend
pnpm install --frozen-lockfile
pnpm test:run
pnpm typecheck
pnpm lint
pnpm build

当前完整基线为后端 217 项、前端 73 项。更详细的测试分层和提交规范见开发指南。

7. 固定验收入口

智能建单真实文本闭环：

python manage.py verify_ticket_intake --username admin

阶段 2 报告：

python manage.py report_stage2_acceptance

阶段 3 报告：

python manage.py report_stage3_acceptance

统一蓝图报告：

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 已健康：

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

7.7 KiB Raw Blame History Unescape Escape