BossAi/run.md

BossAi 运行手册

项目运行事实来源。命令可复制执行,标注 [Docker]/[Native],危险操作标红。

技术栈

层	技术	版本
后端	Python + FastAPI + Uvicorn	Python 3.12 / FastAPI 0.133
前端	React + Vite + TypeScript + Tailwind + shadcn/ui	React 18.3 / Vite 5.4
数据库	PostgreSQL	16.x
模型	Kimi(Moonshot)云端模型,OpenAI 兼容接口	moonshot-v1-8k
包管理	pip(后端)/ npm(前端)	npm 11

首次准备

# 后端依赖(Python 3.12+)
cd /Users/freedak/Documents/AIDashboard/BossAi
pip install fastapi uvicorn pydantic python-dotenv psycopg2

# 数据库初始化(建表 + 种子数据,幂等)
python3 db_init.py

# 前端依赖(Node 18+)
cd web
npm install

# 配置密钥(从 .env.example 复制,填入真实 KIMI_API_KEY)
cp .env.example .env
# 编辑 .env 填入 KIMI_API_KEY

应用启停

后端 API(Native)

# 启动(端口 8000)
cd /Users/freedak/Documents/AIDashboard/BossAi
uvicorn api:app --host 127.0.0.1 --port 8000

# 后台启动
uvicorn api:app --host 127.0.0.1 --port 8000 > /tmp/bossai_uvicorn.log 2>&1 &

# 停止
lsof -ti:8000 | xargs kill

前端 Dev(Native)

# 启动(端口 5173,自动代理 /api → 127.0.0.1:8000)
cd /Users/freedak/Documents/AIDashboard/BossAi/web
npm run dev

# 后台启动
npm run dev > /tmp/bossai_vite.log 2>&1 &

# 停止
lsof -ti:5173 | xargs kill

前端构建

cd /Users/freedak/Documents/AIDashboard/BossAi/web
npm run build      # 产物在 web/dist/
npm run preview    # 预览构建产物
npm run typecheck  # 仅类型检查

前端 2.0 Dev(Native)

# 启动(端口 5174,自动代理 /api → 127.0.0.1:8000)
cd /Users/freedak/Documents/AIDashboard/BossAi/web2
npm install        # 首次
npm run dev

# 后台启动
npm run dev > /tmp/bossai_vite2.log 2>&1 &

# 停止
lsof -ti:5174 | xargs kill

前端 2.0 构建

cd /Users/freedak/Documents/AIDashboard/BossAi/web2
npm run build      # 产物在 web2/dist/
npm run typecheck  # 仅类型检查

数据库迁移(2.0 新增表)

# 执行 migration(幂等,可重复执行)
psql -d mcp -f migrations/001_bossai_v2.sql

# 回滚(慎用,会删除案卡和专家关系数据)
psql -d mcp -f migrations/001_bossai_v2_rollback.sql

端口表

服务	端口	说明
后端 API	8000	FastAPI,健康检查 /health
前端 Dev v1.0	5173	Vite,代理 /api → 8000
前端 Dev v2.0	5174	Vite 2.0,代理 /api → 8000

测试命令

# 后端全部测试(74 项:API + 对抗 + 阅后即焚 + 灾难恢复 + 发布检查 + 法规更新)
cd /Users/freedak/Documents/AIDashboard/BossAi
python3 -m unittest test_bossai test_api test_adversarial test_burn_after_reading test_disaster_recovery test_release_checklist test_regulation -v

# 性能测试
python3 test_performance.py

# 法务评测集(296 个问题,分诊器准确率)
python3 run_eval.py

# 生成评测集(如需重新生成)
python3 gen_eval_set.py

# 前端类型检查 + 构建
cd web
npm run typecheck
npm run build

数据库命令

# 初始化(建表 + 种子数据,幂等可重复执行)
cd /Users/freedak/Documents/AIDashboard/BossAi
python3 db_init.py

# 连接数据库
psql -h localhost -p 5432 -U postgres -d mcp

# 查看表
\dt

# 数据库连接串(代码默认值)
# host=localhost port=5432 dbname=mcp user=postgres
# 可通过环境变量 DATABASE_URL 覆盖
# 限流:每 IP 每秒请求数(默认 20,生产建议 10)
RATE_LIMIT=20

数据表

表	用途
knowledge_docs	法规知识库(法规/案例/模板),RAG 检索源
user_settings	用户设置(key-value 持久化,含权限控制)
expert_rules	专家分配规则(风险等级→专家类型+SLA 时长+自动分配)
review_tickets	人工复核工单(含 SLA 截止时间/状态/专家类型)

环境变量(.env)

变量	说明	示例
KIMI_API_KEY	Kimi/Moonshot API 密钥	sk-xxx
KIMI_MODEL	模型名	moonshot-v1-8k
KIMI_BASE_URL	接口地址	https://api.moonshot.cn/v1
DATABASE_URL	PostgreSQL 连接串	host=localhost port=5432 dbname=mcp user=postgres
RATE_LIMIT	API 限流(每分钟请求数)	20
MESSAGE_ENCRYPTION_KEY	保密模式消息加密密钥(Fernet 格式,生产必须设置)	(用 python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" 生成)
JWT_SECRET	JWT 签名密钥(生产必须修改)	bossai-dev-secret-change-in-prod

密钥仅在 .env 中,已加入 .gitignore,绝不进 Git。 MESSAGE_ENCRYPTION_KEY 未设置时使用开发默认密钥,生产环境必须设置;密钥更换后旧保密历史不可解密。

API 场景参数

/sessions/{sid}/ask 支持 scene 参数路由不同 system prompt:

scene	模块	system prompt 人设
legal	法务参谋	风险等级 + 结论 + 行动 + 证据 + 律师复核
decision	经营决策	情景推演 + 方案对比 + 收益/风险/现金流/推荐
life	生活助理	务实可执行,降低非经营决策负担
emotion	情绪中心	三模式(冷静/陪伴/强力)+ 危机干预

emotion 场景额外支持 emotion_mode 参数:calm / companion / push。

法务场景(scene=legal)自动注入 RAG 上下文:从 knowledge_docs 表检索相关法规,拼入 system prompt,响应中返回 rag_context 数组。

API 端点一览

方法	路径	说明
GET	/health	健康检查
POST	/sessions	创建会话
POST	/sessions/{sid}/ask	提问(非流式,完整响应)
POST	/sessions/{sid}/ask-analyze	事实追问分析(返回追问问题或标记事实已充分)
POST	/sessions/{sid}/ask-stream	提问(SSE 流式,逐 token 返回,支持 fact_answers)
POST	/sessions/{sid}/destroy	隐私急停/销毁
POST	/sessions/{sid}/file	文件上传
GET	/knowledge	知识库列表(支持 doc_type 筛选)
POST	/knowledge	新增知识库文档
GET	/knowledge/search	RAG 检索(中文 2-gram)
DELETE	/knowledge/{id}	删除知识库文档
GET	/settings	读取全部设置
PUT	/settings	批量更新设置
POST	/tickets	创建复核工单(red 自动 urgent)
GET	/tickets	工单列表(支持 status 筛选)
GET	/tickets/{no}	工单详情
PATCH	/tickets/{no}	更新工单状态/分配/结果
GET	/expert-rules	专家分配规则列表
PATCH	/expert-rules/{risk_level}	更新专家规则(SLA/自动分配)
GET	/metrics	可观测性指标(请求数/延迟/模型调用量/销毁统计)
GET	/knowledge/vector-search	向量检索(TF-IDF 余弦相似度)
GET	/sessions/{sid}/destroy-status	销毁状态和日志查询
POST	/summaries/preview	脱敏摘要保存前预览
POST	/summaries	保存脱敏行动摘要
GET	/summaries	列出已保存摘要
GET	/documents/templates	列出可用文书模板
POST	/documents/generate	生成法律文书 DOCX(阅后即焚禁止)
GET	/regulations/check-updates	扫描需更新的法规
POST	/regulations/update	更新法规(自动快照)
GET	/regulations/{id}/versions	列出版本快照
POST	/regulations/{id}/rollback	回滚到指定版本

前后端联调

1. 启动后端:uvicorn api:app --port 8000
2. 启动前端:cd web && npm run dev
3. 访问 http://127.0.0.1:5173
4. 前端通过 Vite 代理 /api → 127.0.0.1:8000,无需 CORS 配置

测试账号

种子数据由 db_init.py 写入,密码已 bcrypt 哈希。普通用户无种子账号,需通过注册接口创建。

管理员(密码 admin123)

手机号	姓名	角色
13800000000	平台管理员	admin

专家(密码 expert123)

手机号规则:139 + 分类码(10法务/20经营/30情绪/40生活) + 6位序号

手机号	姓名	分类	职称	专长
13910000000	张明律师	法务(legal)	高级律师	劳动用工,合同审查,股权纠纷,债权债务
13910000001	李华律师	法务(legal)	执业律师	公司治理,税务合规,商事诉讼
13920000000	王强顾问	经营(decision)	高级经营顾问	战略规划,组织架构,绩效管理,扩张决策
13920000001	赵敏分析师	经营(decision)	财务分析师	财务诊断,融资规划,现金流管理
13930000000	陈静咨询师	情绪(emotion)	国家二级心理咨询师	焦虑疏导,压力管理,决策疲劳,创业者心理
13930000001	刘阳教练	情绪(emotion)	情绪教练	情绪识别,沟通改善,团队氛围
13940000000	周婷顾问	生活(life)	生活规划师	时间管理,家庭关系,健康管理
13940000001	吴昊教练	生活(life)	商务礼仪教练	商务礼仪,出差规划,形象管理

普通用户

无种子账号,通过注册接口创建:

# 注册示例(密码至少 6 位)
curl -X POST http://127.0.0.1:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"phone":"13900000001","password":"user123","name":"测试老板"}'

排错

问题	原因	修复
前端提问返回 model: local-triage	后端未加载 .env 或 KIMI_API_KEY 无效	确认 .env 存在且密钥有效,重启后端
前端 model: kimi 但 answer 为 null	Kimi 调用异常被捕获	查后端日志,检查网络/密钥/额度
前端 5173 无法访问	Vite 未启动或端口占用	lsof -ti:5173 | xargs kill 后重启
前端 health 显示后端不可达	后端 8000 未启动	启动 uvicorn
销毁后提问返回 410	会话已销毁(预期行为)	重新创建会话

部署备份

• 前端构建产物 web/dist/ 为静态包,可由 nginx 或 FastAPI 静态托管
• 生产部署建议:nginx 托管前端静态包 + 反代 /api → uvicorn
• 数据库:PostgreSQL(已接入),知识库/设置/工单/摘要持久化
• CI/CD:GitHub Actions(.github/workflows/ci.yml),后端测试 + 前端构建

数据库备份

# 手动备份(压缩,可选 GPG 加密)
./backup.sh

# 加密备份(需先配置 GPG key)
./backup.sh ./backups user@example.com

# crontab 每天 2 次备份
0 2,14 * * * cd /Users/freedak/Documents/AIDashboard/BossAi && ./backup.sh >> backups/backup.log 2>&1

# 恢复
gunzip backups/bossai_XXXXXXXX_XXXXXX.sql.gz
psql -h localhost -U postgres -d mcp < backups/bossai_XXXXXXXX_XXXXXX.sql