chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
684261f4b4767ba4b4572106ae8d9d0d88f7c509
hunjing/docker/README.md
T
chenxin 144415247e M4 收口：神识用户面与计量闭环——BYOK/配额三段式/usage 落库/Anthropic+Gemini 适配器/神识阁 
- 神识 Go：store 双实现（PG 自动建表+60s 就绪重试 / 内存回退）承载 usage_logs·byok_keys·quota_balances；BYOK 密钥库（AES-GCM 加密、API 脱敏、撤回即失效、主密钥未配置 fail-closed）；配额三段式（预扣 max_tokens 钳位 1M→结算实际 token→全败幂等退款，HJ-2004）；计量归属（IR user_id→usage_logs，/me/usage 用户维度聚合+配额总览，/admin/usage/sample 对账抽样）；Anthropic/Gemini 出站适配器（SSE 解析、system 提升、用量映射）；stub 端点补名修复计量空 endpoint
- IR 契约：user_id/byok_key_id 双端同步（Go types.go + Py types.py）
- 灵台：runs.owner_id（迁移 005，server_default 兼容存量）经 kernel 全链透传为 IR user_id；shenshi_client 扩展用户面方法（X-Hunjing-User-Id 代理，Echo 桩带内存实现）；/me/byok-keys 登记·列表·撤回与 /me/usage 端点（4 用例）
- 前端神识阁（/models 重建）：偏好（生成参数表单）/自带密钥（登记加密保存、脱敏列表、撤回二次确认）/用量（聚合表+配额进度条）三区；me API 库+mock+5 用例；侧栏恢复入口
- 配置与部署：.env.example 增 SHENSHI_DATABASE_URL/SHENSHI_BYOK_MASTER_KEY/SHENSHI_USER_BUDGET_TOKENS；compose 神识容器接自有库（init-shenshi.sql 预建 hunjing_shenshi，与灵台不共库共表）
- 证据：Go 34 用例（BYOK 独占/配额拒绝/结算退款/归属聚合）、后端 532、前端 210、BFF 4 全绿；跨进程 E2E 四场景（灵台 HttpShenshiClient→真 Go 神识：登记脱敏/BYOK 独占不可达整体失败/用量归属聚合/撤回即失效）通过；rewrite-plan M4 标记完成、能力矩阵神识行升已验证
2026-08-27 18:39:17 +08:00

146 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 魂镜 Docker 部署
本目录是魂镜的容器化编排入口。本地开发默认使用 SQLite，**无需**启动本文件；如需模拟正式环境或进行生产部署，按本文说明使用。
## 编排结构（基础设施 / 应用 解耦）
编排按职责拆分为两个文件，通过共享网络 `hunjing-net` 互通：
| 文件 | 职责 | 网络 / 卷 |
| --- | --- | --- |
| `docker-compose.infra.yml` | 数据基础设施（关系库 / 缓存 / 向量 / 图库 / 对象存储 / 备份） | **创建并拥有** `hunjing-net` 网络与全部命名卷 |
| `docker-compose.app.yml` | 应用层（后端 / 前端 / 反向代理） | 以 `external` 引用 `hunjing-net`，用 bind mount 持久化日志/数据 |
> 应用层依赖 `hunjing-net` 网络，**必须先启动基础设施**（首次启动会创建该网络）。容器名统一以 `hunjing-` 开头，两个文件归属同一 compose project（`name: hunjing`）。
### 基础设施服务（`docker-compose.infra.yml`）
| 服务 | 镜像 | 内存上限 / 预留 | 用途 |
| --- | --- | --- | --- |
| `hunjing-postgres` | `postgres:16-alpine` | 512M / 128M | 正式环境关系型数据库 |
| `hunjing-redis` | `redis:7-alpine` | 256M / 64M | 缓存 / 后台任务队列 |
| `hunjing-neo4j` | `neo4j:5-community` | 1G / 256M | 图数据库（原型 / 中小规模，默认） |
| `hunjing-nebula-metad` | `vesoft/nebula-metad:v3.6.0` | 512M / 128M | NebulaGraph 元数据（需 `--profile nebulagraph`） |
| `hunjing-nebula-storaged` | `vesoft/nebula-storaged:v3.6.0` | 1G / 256M | NebulaGraph 存储 |
| `hunjing-nebula-graphd` | `vesoft/nebula-graphd:v3.6.0` | 512M / 128M | NebulaGraph 查询（暴露 9669） |
| `hunjing-nebula-console-init` | `vesoft/nebula-console:v3.6.0` | 256M / 64M | 一次性注册 hosts / 建 space |
| `hunjing-etcd` | `quay.io/coreos/etcd:v3.5.16` | 512M / 128M | Milvus 元数据依赖 |
| `hunjing-minio` | `minio/minio:RELEASE...` | 512M / 128M | Milvus 存储 + 对象存储 |
| `hunjing-milvus` | `milvusdb/milvus:v2.4.17` | 2G / 512M | 向量检索（暴露 19530） |
| `hunjing-attu` | `zilliztech/attu:v2.4` | 256M / 64M | Milvus Web 可视化（`:8001`） |
| `hunjing-pg-backup` | `postgres:16-alpine` | 256M / 64M | PostgreSQL 备份 / 恢复（需 `--profile backup`） |
### 应用服务（`docker-compose.app.yml`）
| 服务 | 镜像 | 内存上限 / 预留 | 用途 |
| --- | --- | --- | --- |
| `hunjing-backend` | 本目录 `backend/Dockerfile` 构建 | 1G / 256M | FastAPI 后端（`:8000`） |
| `hunjing-frontend` | 本目录 `frontend/Dockerfile` 构建 | 512M / 128M | Next.js 前端（`:3000`） |
| `hunjing-sandbox` | 本目录 `sandbox/Dockerfile` 构建 | 512M / 1.0CPU / 256pids | 安全沙箱（`:8090`，需 `--profile sandbox`） |
| `hunjing-yuanqi` | 本目录 `yuanqi/Dockerfile` 构建 | 1G / 4G | 本地推理引擎（`:11434`，需 `--profile yuanqi`） |
| `hunjing-nginx` | `nginx:1.27-alpine` | 128M / 32M | 反向代理，统一入口 80（需 `--profile nginx`） |
> 内存上限为本地模拟正式环境的保守默认值（写在各服务 `deploy.resources`），可按宿主机规格调整。Neo4j / NebulaGraph 二选一；本地开发向量检索使用内嵌 ChromaDB（`db/chroma`），与本编排无关。
## 启动顺序
- 基础设施 `up` 创建 `hunjing-net` 网络；应用层以 external 引用，必须后启动。
- 后端镜像内置 `wait-for-it.sh` + `entrypoint.sh`：容器启动时按 `*_ENABLED` / `DATABASE_TYPE` 开关**动态等待依赖**（pgsql 必等 postgres；redis / milvus / neo4j / nebula 仅在对应开关启用时等待），超时只告警不阻断，再 `uv run python -m app.main`。因此即便先起应用层，后端也会等待数据库就绪而非立即失败。
## 前置准备
1. 在项目根目录复制并填写环境变量：
```bash
cp .env.example .env
```
重点修改：`POSTGRES_PASSWORD`、`SHENSHI_ENDPOINTS`（神识模型端点目录，JSON 数组，示例见 `.env.example`）、`SHENSHI_BYOK_MASTER_KEY`（启用 BYOK，可选）。神识自有库 `hunjing_shenshi` 由 `docker/postgres/init-shenshi.sql` 首次初始化时自动创建。若使用 NebulaGraph，确认 `GRAPH_DB_TYPE=nebulagraph`。
2. 应用层的 `environment` 会自动覆盖容器网络服务发现地址（如 `POSTGRES_HOST=hunjing-postgres`），无需手动改 `.env` 里的 `127.0.0.1`。
## 常用命令
```bash
# 1) 先启动基础设施（首次会创建 hunjing-net 网络与命名卷）
docker compose -f docker/docker-compose.infra.yml up -d
# 2) 再启动应用层（构建前后端镜像）
docker compose -f docker/docker-compose.app.yml up -d --build
# 一键：基础设施 + 应用（&& 保证顺序）
docker compose -f docker/docker-compose.infra.yml up -d && \
docker compose -f docker/docker-compose.app.yml up -d --build
```
按需 / 辅助命令：
```bash
# 仅启动部分基础设施
docker compose -f docker/docker-compose.infra.yml up -d hunjing-postgres hunjing-redis
# NebulaGraph（需带 --profile，会自动带起 metad / storaged）
docker compose -f docker/docker-compose.infra.yml --profile nebulagraph up -d hunjing-nebula-graphd hunjing-nebula-console-init
# Attu（Milvus 可视化）：启动后访问 http://localhost:${ATTU_PORT:-8001}
docker compose -f docker/docker-compose.infra.yml up -d hunjing-attu
# 仅启动后端 / 前端
docker compose -f docker/docker-compose.app.yml up -d hunjing-backend
# 日志
docker compose -f docker/docker-compose.app.yml logs -f hunjing-backend
# 停止应用 / 停止基础设施（保留数据卷）
docker compose -f docker/docker-compose.app.yml down
docker compose -f docker/docker-compose.infra.yml down
# 清除基础设施数据卷（谨慎，会丢失数据库与对象存储数据）
docker compose -f docker/docker-compose.infra.yml down -v
```
## 反向代理（可选，`--profile nginx`）
对外只暴露 80，`/api/*` 与 SSE 走后端、其余走前端，配置见 `docker/nginx/nginx.conf`。启用：
```bash
docker compose -f docker/docker-compose.app.yml --profile nginx up -d hunjing-nginx
# 访问 http://localhost:${NGINX_PORT:-80}
```
> 启用 nginx 后，浏览器可直接访问 80 端口（同源，无跨域）；后端 8000 / 前端 3000 端口可不再对外暴露（按需从 compose 删除其 `ports`）。
## 备份与恢复（`--profile backup`）
PostgreSQL 备份脚本 `docker/backup/backup-postgres.sh`：`pg_dump` 导出 + gzip 压缩 + 按 `BACKUP_RETAIN_DAYS`（默认 7）清理过期备份，产物落在项目根 `backups/`（已加入 `.gitignore`）。
```bash
# 备份
docker compose -f docker/docker-compose.infra.yml --profile backup run --rm hunjing-pg-backup
# 恢复（覆盖现有数据，覆盖 entrypoint 并指定 RESTORE_FILE）
docker compose -f docker/docker-compose.infra.yml --profile backup run --rm \
-e RESTORE_FILE=hunjing-20260620-000000.sql.gz \
--entrypoint /bin/sh hunjing-pg-backup /backup/backup-restore.sh
```
> 定时备份可结合主机 crontab 定期执行上述备份命令（脚本自身已做保留期清理）。`hunjing-postgres` 的 `PG*` 凭据由 `.env` 注入。
## 与 `.env` 的关系
- `hunjing-backend` 通过 `env_file: ../.env` 注入全部业务配置（含模型密钥）；`entrypoint.sh` 读取其中的 `*_ENABLED` 决定等待哪些依赖。
- `environment` 段覆盖容器网络服务发现地址，优先级高于 `env_file`，保证后端连到容器内服务而非 `127.0.0.1`。
- 是否真正连接 Redis / Milvus / Neo4j / NebulaGraph，仍由 `REDIS_ENABLED` / `VECTOR_DB_ENABLED` / `GRAPH_DB_ENABLED`（配合 `GRAPH_DB_TYPE`）显式开关控制（与 `docs/architecture/system-architecture.md` 一致：不能仅凭地址是否存在隐式启用）。
## 数据持久化
- 基础设施命名卷（pg / redis / neo4j / nebula / etcd / minio / milvus）由 `docker-compose.infra.yml` 拥有。
- 应用的 `logs/`、`db/`、`storage/`、`config/` 通过 bind mount 挂载到项目根目录（`config` 为只读挂载）。
- 备份产物 `backups/` 为 bind mount，落在项目根。
## 备注
- 本地开发首选 SQLite + `uv run python -m app.main` + `pnpm dev`，无需 Docker；本编排面向**正式环境 / 模拟正式环境**。
- NebulaGraph / 备份 / nginx 均用 `profiles` 隔离，默认不随 `up` 拉起。
- 本文件未提供本地开发覆盖配置；如需差异化本地编排，可在 `docker/` 下新增 `*.local.yml`（已被 `.gitignore` 忽略）。
Reference in new issue View Git Blame Copy Permalink