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

   ```bash
   cp .env.example .env
   ```

   重点修改：`POSTGRES_PASSWORD`、各模型 provider 的 `*_API_KEY`、`config/models.yaml`（由 `config/models.example.yaml` 复制）。若使用 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` 忽略）。