hunjing/docker/README.md

魂镜 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. 在项目根目录复制并填写环境变量：

   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。

常用命令

# 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

按需 / 辅助命令：

# 仅启动部分基础设施
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。启用：

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）。

# 备份
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 忽略）。