From 48b52ca21c885b91c5465e001f2c8ba0884ff957 Mon Sep 17 00:00:00 2001 From: cnphpbb Date: Fri, 19 Jun 2026 14:49:22 +0800 Subject: [PATCH] feat(honcho): add honcho self-hosted deployment stack --- honcho/env.cfg.example | 67 ++++++++ honcho/readme.md | 355 ++++++++++++++++++++++++++++++++++++++++- honcho/stack.yml | 153 ++++++++++++++++++ 3 files changed, 574 insertions(+), 1 deletion(-) diff --git a/honcho/env.cfg.example b/honcho/env.cfg.example index e69de29..ed473a5 100644 --- a/honcho/env.cfg.example +++ b/honcho/env.cfg.example @@ -0,0 +1,67 @@ +# ============================================================ +# Honcho Self-Hosted 部署 — 公共环境变量（不含敏感信息） +# 复制为 env.cfg 后填入真实值，env.cfg 已被 .gitignore 忽略 +# ============================================================ + +# ============================================================ +# 镜像版本 +# ============================================================ +# Honcho 主仓库 git ref（源码 build 用，可填 tag / branch / SHA） +HONCHO_VERSION=main +# PostgreSQL 大版本号（pgvector 镜像 tag 后缀，必须与镜像仓库支持的 tag 对应） +HONCHO_DB_VERSION=18 +# Redis 大版本号 +HONCHO_REDIS_VERSION=8 + +# 镜像仓库（默认公共镜像；自建私有 hub 可改 hub.tp229.com:3500/...） +HONCHO_DB_IMAGE=pgvector/pgvector +HONCHO_REDIS_IMAGE=redis + +# ============================================================ +# PostgreSQL 数据库 +# ============================================================ +HONCHO_DB_USER=honcho +HONCHO_DB_NAME=honcho +# scram-sha-256 比 md5 安全；与 POSTGRES_INITDB_ARGS --auth-host 同步 +POSTGRES_HOST_AUTH_METHOD=scram-sha-256 + +# ============================================================ +# 宿主机数据卷路径（必须 WSL/Linux ext4 原生 fs，不能放 /mnt/9P） +# 9P drvfs 的 fsync 不可靠，会导致 PG 数据损坏 +# ============================================================ +Volumes_Path=/data/Volumes/honcho + +# ============================================================ +# 服务端口（宿主机:容器，全部绑定 0.0.0.0 供 LAN 访问） +# 5432 与 hindsight/dbSer 撞车，多服务共存时改 HONCHO_DB_PORT 区分 +# ============================================================ +HONCHO_API_PORT=8000 +HONCHO_DB_PORT=5432 +HONCHO_REDIS_PORT=6379 + +# ============================================================ +# Honcho 应用配置 +# ============================================================ +HONCHO_LOG_LEVEL=INFO +# 本地 LAN 自用可设 false；公网暴露必须改 true +HONCHO_AUTH_USE_AUTH=false +HONCHO_NAMESPACE=honcho +# 关闭可省 embedding 费用（但失去语义检索能力） +HONCHO_EMBED_MESSAGES=true +HONCHO_EMBEDDING_MODEL=text-embedding-3-small +# deriver 必须用支持 tool calling 的模型 +HONCHO_DERIVER_MODEL=gpt-5.4-mini +HONCHO_DERIVER_WORKERS=1 + +# ============================================================ +# LLM（OpenAI 兼容协议；可换 OpenRouter / vLLM / Ollama 等端点） +# deriver 启动时强校验 API Key 非空，占位符会反复重启 +# ============================================================ +HONCHO_LLM_BASE_URL=https://api.openai.com/v1 + +# ============================================================ +# 敏感值（必填，env.cfg 不提交）— 在 .gitignore 已忽略 +# ============================================================ +# HONCHO_LLM_API_KEY=<你的 OpenAI key 或兼容端点 key> +# HONCHO_DB_PASSWORD=<强密码，不要带特殊字符，避免 URI 编码问题> +# HONCHO_AUTH_JWT_SECRET=<仅 AUTH_USE_AUTH=true 时需要；用 python scripts/generate_jwt_secret.py 生成> \ No newline at end of file diff --git a/honcho/readme.md b/honcho/readme.md index a45eb7c..f60483f 100644 --- a/honcho/readme.md +++ b/honcho/readme.md @@ -1 +1,354 @@ -# Honcho部署栈 +# Honcho Self-Hosted 部署栈 + +[plastic-labs/honcho](https://github.com/plastic-labs/honcho) 是 Plastic Labs 开源的 **AI Agent 长期记忆后端**（v3.0.x，AGPL-3.0）。Hermes Agent 用它做跨会话的用户上下文管理（peer-centric 记忆、推理、检索）。本目录部署的是 **honcho-self-hosted**：基于 [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) 配置的本地化版本，集成到 `deploy.stack` 仓库规范下。 + +与官方 `docker-compose.yml.example` 的差异：本目录用 **PostgreSQL 18 + Redis 8**（非官方默认的 pg15/redis 8.2）、`${Volumes_Path}` bind 挂载（非 docker volume）、固定到内网可访问的端口。 + +## 目录结构 + +| 文件 | 说明 | +|------|------| +| `stack.yml` | Docker Compose 主文件（4 服务：api + deriver + database + redis） | +| `env.cfg.example` | 公共环境变量模板（不含敏感信息，可提交） | +| `env.cfg` | **敏感配置（gitignore，不提交）** — 实际部署时从 example 复制后填密码/API Key | +| `readme.md` | 本文档 | + +## 架构 + +```mermaid +flowchart TB + subgraph src["源码构建期（无运行时 bind）"] + source["${Volumes_Path}/honcho/source
git clone plastic-labs/honcho
api/deriver Dockerfile build context"] + end + + subgraph run["运行时 — honcho-net bridge"] + api["honcho-api
FastAPI 主服务
:8000 (0.0.0.0)
build from source"] + deriver["honcho-deriver
后台推理 worker
消息→观察→peer representation
build from source"] + database["honcho-database
pgvector/pgvector:pg18
:5432 (0.0.0.0)
scram-sha-256"] + redis["honcho-redis
redis:8
:6379
CACHE_URL"] + end + + subgraph host["宿主机持久化 (WSL ext4)"] + pgdata["${Volumes_Path}/pgdata
(bind mount)"] + redisdata["${Volumes_Path}/redis
(bind mount)"] + end + + subgraph external["外部调用方"] + hermes["Hermes Agent
memory.provider=honcho"] + sdk["Python / TS SDK
(honcho-ai / @honcho-ai/sdk)"] + tools["DBeaver / psql
PG 5432 直连"] + end + + source -.->|docker build
首次 5-10 min| api + source -.->|docker build| deriver + + hermes -->|HTTP :8000| api + sdk -->|HTTP :8000| api + tools -->|:5432| database + + api -->|:5432| database + deriver -->|:5432| database + api -->|:6379| redis + deriver -->|:6379| redis + deriver -.->|轮询
pending messages| api + + database --- pgdata + redis --- redisdata + + classDef ext fill:#e1f5ff,stroke:#01579b,color:#000 + classDef build fill:#fff3e0,stroke:#e65100,color:#000 + classDef data fill:#f3e5f5,stroke:#4a148c,color:#000 + classDef host fill:#e8f5e9,stroke:#1b5e20,color:#000 + + class hermes,sdk,tools ext + class source build + class api,deriver,database,redis ext + class pgdata,redisdata data +``` + +> **源码不在运行时 bind mount**：api/deriver 通过 `build: context: .` 从 `git clone` 的源码目录（`${Volumes_Path}/honcho/source`）构建，**不**挂源码进运行容器。`source/` 仅作为构建缓存，方便后续 `git pull` 后增量 rebuild。 + +**四个服务的职责：** + +| 服务 | 角色 | 关键依赖 | +|------|------|----------| +| `api` | FastAPI 主服务，对外提供 REST API（端口 8000） | database、redis | +| `deriver` | **后台推理 worker**：消息→观察→peer representation→session 摘要 | api（健康后才起）、database、redis | +| `database` | PostgreSQL + pgvector 扩展，存所有 messages、peers、workspaces | — | +| `redis` | 缓存层（`CACHE_URL=redis://redis:6379/0`） | — | + +**⚠️ deriver 不可省**：没它，消息能写入 DB，但不会生成记忆、不会提取观察、不会做 session 摘要。Honcho 退化成纯 KV 存储。 + +## 端口 + +| 端口 | 服务 | 用途 | +|------|------|------| +| `8000` | api | Honcho REST API（供 Hermes / Python SDK / TypeScript SDK 调用） | +| `5432` | database | PostgreSQL 对外访问（DBeaver、psql 等工具连接） | +| `6379` | redis | Redis 对外访问（一般无需直连） | + +宿主机端口可通过 `env.cfg` 中的 `HONCHO_API_PORT`、`HONCHO_DB_PORT`、`HONCHO_REDIS_PORT` 自定义。 + +## 环境变量 + +### 公共变量（`env.cfg.example`） + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `HONCHO_VERSION` | `main` | Honcho 主仓库 git ref（tag / branch / SHA 都可；源码 build 用） | +| `HONCHO_BRANCH` | `main` | 源码 checkout 分支（`HONCHO_VERSION` 不是 branch 时生效） | +| `HONCHO_DB_VERSION` | `18` | PostgreSQL 大版本号（pgvector 镜像 tag 后缀） | +| `HONCHO_REDIS_VERSION` | `8` | Redis 大版本号 | +| `HONCHO_DB_IMAGE` | `pgvector/pgvector` | DB 镜像仓库 | +| `HONCHO_REDIS_IMAGE` | `redis` | Redis 镜像仓库 | +| `HONCHO_DB_USER` | `honcho` | PostgreSQL 用户名 | +| `HONCHO_DB_NAME` | `honcho` | PostgreSQL 数据库名 | +| `HONCHO_DB_PASSWORD` | `honcho` | PostgreSQL 密码（**部署时必须改**） | +| `POSTGRES_HOST_AUTH_METHOD` | `scram-sha-256` | PG 认证方式 | +| `Volumes_Path` | `/data/Volumes/honcho` | 宿主机持久化数据根路径 | +| `HONCHO_API_PORT` | `8000` | API 宿主机端口 | +| `HONCHO_DB_PORT` | `5432` | PostgreSQL 宿主机端口 | +| `HONCHO_REDIS_PORT` | `6379` | Redis 宿主机端口 | +| `HONCHO_LOG_LEVEL` | `INFO` | Honcho 日志级别 | +| `HONCHO_AUTH_USE_AUTH` | `false` | 是否启用 JWT 鉴权（生产建议 `true`） | +| `HONCHO_NAMESPACE` | `honcho` | 全局命名空间前缀 | +| `HONCHO_EMBED_MESSAGES` | `true` | 是否对消息做向量化（关闭可省 embedding 费用） | +| `HONCHO_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding 模型名 | +| `HONCHO_DERIVER_MODEL` | `gpt-5.4-mini` | Deriver 用的 LLM 模型（必须支持 tool calling） | +| `HONCHO_LLM_BASE_URL` | `https://api.openai.com/v1` | LLM API Base URL（OpenAI 兼容端点即可） | +| `HONCHO_DERIVER_WORKERS` | `1` | Deriver worker 数 | + +### 敏感变量（`env.cfg`，不提交） + +| 变量 | 说明 | +|------|------| +| `HONCHO_LLM_API_KEY` | LLM API Key（**必填**，server 启动检查，没它起不来） | +| `HONCHO_DB_PASSWORD` | PostgreSQL 密码（**必填**，用强密码） | +| `HONCHO_AUTH_JWT_SECRET` | JWT 密钥（仅在 `HONCHO_AUTH_USE_AUTH=true` 时需要；用 `python scripts/generate_jwt_secret.py` 生成） | + +**关键约束**：Honcho 启动时会**校验** `HONCHO_LLM_API_KEY` 非空 — 缺失则立刻退出。这意味着 `env.cfg` 里这一项**不能用占位符**（如 `sk-placeholder`），必须填真实值，否则 `docker compose up -d` 后 deriver 容器会反复重启。 + +## 部署步骤 + +### 首次部署 + +```bash +# 1. 准备数据目录（必须原生 ext4，不能放 9P drvfs） +sudo mkdir -pv /data/Volumes/honcho/{pgdata,redis,source} +sudo chown -R 999:999 /data/Volumes/honcho/pgdata +sudo chown -R 999:999 /data/Volumes/honcho/redis + +# 2. 复制 env 模板并填入真实值 +cp honcho/env.cfg.example honcho/env.cfg +$EDITOR honcho/env.cfg +# 必填：HONCHO_LLM_API_KEY（不能用空值/默认值，否则 deriver 起不来） +# 必填：HONCHO_DB_PASSWORD（改成强密码） +# 推荐改：HONCHO_DB_USER / HONCHO_DB_NAME（默认值 honcho 仅 dev 可用） + +# 3. 拉镜像（PG + Redis 是预构建；api/deriver 从源码 build） +docker compose --env-file ./honcho/env.cfg -f ./honcho/stack.yml pull + +# 4. 构建 + 启动（首次 api/deriver 构建需 5-10 分钟，依赖网络） +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml up -d --build +``` + +### 验证 + +```bash +# 容器状态（必须 4 个都 healthy） +docker ps -f name=honcho + +# API 健康检查 +curl -s http://localhost:8000/health + +# 数据库连接 +docker exec -it honcho-database psql -U honcho -d honcho -c '\dt' + +# pgvector 扩展确认 +docker exec -it honcho-database psql -U honcho -d honcho \ + -c "SELECT extname FROM pg_extension WHERE extname='vector';" + +# Redis 连接 +docker exec -it honcho-redis redis-cli ping +# 期望输出：PONG + +# deriver 日志（看是否成功处理消息） +docker logs -f honcho-deriver --tail 50 + +# 端口监听 +ss -tlnp | grep -E '8000|5432|6379' +``` + +### 停止/重启 + +```bash +# 停止（保留数据） +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml stop + +# 完全销毁（**数据不删**，bind 挂载保留在宿主机） +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml down + +# 重启 +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml restart +``` + +## 关键设计决策 + +| 决策点 | 决定 | 原因 | +|--------|------|------| +| 镜像源 | api/deriver 从 [plastic-labs/honcho](https://github.com/plastic-labs/honcho) **源码 build** | 官方**没有预构建镜像**，Docker Hub 也没 — 必须 build | +| DB 版本 | PostgreSQL 18（pgvector 镜像 `pg18` tag） | 用户指定，比官方默认 pg15 新 | +| Redis 版本 | Redis 8 | 用户指定 | +| 数据卷方案 | bind 挂载到 `${Volumes_Path}/{pgdata,redis,source}` | 直观、可直接 `rsync`/`pg_dump`、跨机迁移用 `tar` 整个目录即可 | +| 端口绑定 | 0.0.0.0，含 DB 5432 | PVE LAN 上其他 VM 也可访问；DB 端口暴露方便外部工具（DBeaver 等）连接 | +| 认证 | 默认 `HONCHO_AUTH_USE_AUTH=false`（dev 模式） | 本地 LAN 自用，跳过 JWT 校验；公网暴露必须改 `true` | +| LLM 默认 | `gpt-5.4-mini` + `text-embedding-3-small` | OpenAI 兼容、成本低；可换 OpenRouter / vLLM / Ollama 等任意端点 | +| Honcho 版本 | 默认 `main`（源码 build），可锁 tag 如 `v3.0.10` | 当前最新稳定版 v3.0.x，支持 peer card、dialectic、dream consolidation | +| deriver 必须 | api + deriver 双容器 | deriver 是后台推理 worker，没它记忆功能不工作 | +| PG 认证 | `scram-sha-256` | 比 md5 更安全，`POSTGRES_INITDB_ARGS` 同步设置 `--auth-host` | + +## 关键陷阱（必读） + +### 1. 首次构建时间长且需要 BuildKit + +```bash +# 必须开启 BuildKit（默认 20.10+ 已启用，但确认下） +DOCKER_BUILDKIT=1 docker compose ... +``` + +- 首次 build api/deriver 镜像需 **5-10 分钟**（拉源码 + uv sync Python 依赖 + pip install ~300MB） +- 后续增量构建快（除非 Honcho 自身依赖变更） +- 构建失败常见原因：网络拉 `astral-sh/uv` 慢、Python wheel 编译失败 — 配置 Docker 镜像加速 + +### 2. deriver 必须健康，否则记忆不工作 + +如果只看到 `honcho-api` 是 `healthy` 但 `honcho-deriver` 反复重启或卡在 startup，**消息会写入但不会产生任何记忆**。检查： + +```bash +docker logs honcho-deriver --tail 100 | grep -iE "error|fatal" +``` + +deriver 起不来最常见原因： +- `HONCHO_LLM_API_KEY` 为空/无效 — server 启动立即校验 +- LLM 模型不支持 tool calling — deriver 强依赖 function calling +- LLM API base URL 配错（如少了 `/v1` 后缀） + +### 3. AGPL-3.0 传染条款 + +Honcho 是 **AGPL-3.0**，对网络服务部署有"用户可获取源码"的要求。本地 LAN 自用不触发，但若对外提供服务（哪怕只是 API 反代），需考虑： +- 对外服务时 `AUTH_USE_AUTH=true` + 公开 `AUTH_JWT_SECRET` 之外，**还需要向用户公开 Honcho 源码修改** +- 详见 [AGPL-3.0 §13](https://www.gnu.org/licenses/agpl-3.0.html) + +### 4. WSL 9P `fsync` 陷阱 + +**PG/Redis 数据绝不能放 `/mnt/c/`、`/mnt/d/` 等 9P drvfs 路径**。`${Volumes_Path}` 必须指向 WSL 原生 ext4（`/data/Volumes/honcho`），否则可能静默数据损坏。 + +### 5. `POSTGRES_HOST_AUTH_METHOD=trust` 已删除 + +honcho-self-hosted 相对官方 compose 的一个改进：**移除了**`trust` 认证（官方默认的 dev 用法），改用强密码 + scram-sha-256。生产环境务必保留这个设置。 + +## 故障排查 + +| 症状 | 排查命令 | +|------|----------| +| api 容器起不来 | `docker logs -f honcho-api` — 通常是 `LLM_OPENAI_API_KEY is required` 或 DB 连接失败 | +| deriver 反复重启 | `docker logs -f honcho-deriver` — 检查 LLM key、模型名、base URL | +| DB 连不上（容器内） | `docker exec -it honcho-database psql -U honcho -d honcho` | +| DB 连不上（外部工具） | 确认 `HONCHO_DB_PORT` 已映射、`ss -tlnp` 检查 5432 监听；密码含特殊字符试改简单 | +| API `/health` 502/超时 | 检查 deriver 是否 healthy（`depends_on` 会卡住 api） | +| pgvector 扩展缺失 | `docker exec -it honcho-database psql -U honcho -d honcho -c "CREATE EXTENSION IF NOT EXISTS vector;"` | +| 端口冲突 | `ss -tlnp \| grep -E '8000\|5432\|6379'` — 检查是否与 hindsight/dbSer 等服务撞车 | +| 慢查询 / DB 锁 | `docker exec -it honcho-database psql -U honcho -d honcho -c "SELECT * FROM pg_stat_activity;"` | +| 密码含特殊字符连不上 | `HONCHO_DB_PASSWORD` 最好只用字母数字，避免 URI 编码问题；如必须用，把 URL 里特殊字符 percent-encode | + +## 与 Hermes Agent 集成 + +Hermes plugin 通过 HTTP 调用 Honcho 的 REST API（`localhost:8000`），不直连 DB。配置在 `~/.hermes/config.yaml`： + +```yaml +memory: + provider: honcho + honcho: + api_url: http://localhost:8000 + # api_key 不需要（本地自托管，AUTH_USE_AUTH=false） + workspace_id: hermes + auto_recall: true + auto_retain: true +``` + +切换命令：`hermes config set memory.provider honcho` + +**与 Hindsight 的差异**： +- Hindsight 强调 **跨会话长期记忆**（基于时序、bi-temporal） +- Honcho 强调 **peer-centric 用户画像**（多 peer 互观察、推理、deduction） +- 两者可并存；Hermes 当前用 Honcho 做主记忆层，Hindsight 作为补充 + +## 备份与恢复 + +### 自动备份（推荐） + +`backup.job`（待补）— 用 `pg_dump` 热备份 PG + `redis-cli BGSAVE` 备份 Redis。接入 cron： + +```bash +# /etc/cron.d/honcho-backup +30 3 * * * /path/to/deploy.stack/honcho/backup.job >> /var/log/honcho-backup.log 2>&1 +``` + +或参考 `crontab/` 目录的统一任务管理方式。 + +### 手动备份 + +```bash +# PG 热备份 +docker exec honcho-database pg_dump -U honcho -d honcho | \ + gzip > /data/Volumes/honcho/backups/honcho_$(date +%Y%m%d).sql.gz + +# Redis 快照 +docker exec honcho-redis redis-cli BGSAVE +# 触发后 /data/Volumes/honcho/redis/dump.rdb 是最新快照 +``` + +### 恢复 + +```bash +# 从 pg_dump 恢复（需要先创建空 DB） +gunzip -c /data/Volumes/honcho/backups/honcho_20260619.sql.gz | \ + docker exec -i honcho-database psql -U honcho -d honcho + +# 从 Redis dump 恢复 +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml stop honcho-redis +sudo cp /data/Volumes/honcho/backups/dump.rdb /data/Volumes/honcho/redis/dump.rdb +sudo chown 999:999 /data/Volumes/honcho/redis/dump.rdb +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml start honcho-redis +``` + +## 升级 + +```bash +# 1. 拉取最新源码（在 host 上或临时容器） +cd /data/Volumes/honcho/source && git pull + +# 2. 重建 api + deriver 镜像 +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml build api deriver + +# 3. 滚动重启 +docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml up -d + +# 4. 跑迁移（honcho entrypoint.sh 会自动执行；若需手动跑） +docker exec -it honcho-api sh -c "cd /app && .venv/bin/alembic upgrade head" +``` + +**PG 大版本升级**（如未来 18→19）需 `pg_dump` → 新版本空 DB → restore，**不能直接换 tag**。 + +## 相关文档 + +- [plastic-labs/honcho](https://github.com/plastic-labs/honcho) — 上游仓库 +- [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) — 一键安装器，本目录配置基于此 +- [Honcho 自托管官方文档](https://honcho.dev/docs/v3/contributing/self-hosting) +- `hindsight/readme.md` — 同仓库姊妹服务，部署模式高度相似 +- 仓库根 `AGENTS.md` — `deploy.stack` 项目规范 +- `crontab/` — 定时任务集成参考 + +## 已知限制 + +详见上文 [关键陷阱](#关键陷阱必读) — 主要为：无预构建镜像（必须源码构建）/ AGPL-3.0 传染 / deriver 强依赖 LLM。 \ No newline at end of file diff --git a/honcho/stack.yml b/honcho/stack.yml index e69de29..fd8f3d1 100644 --- a/honcho/stack.yml +++ b/honcho/stack.yml @@ -0,0 +1,153 @@ +# Honcho Self-Hosted 部署栈 +# ============================================================ +# 部署前准备（仅首次）： +# mkdir -pv ${Volumes_Path}/{pgdata,redis,source} +# sudo chown -R 999:999 ${Volumes_Path}/pgdata +# sudo chown -R 999:999 ${Volumes_Path}/redis +# git clone https://github.com/plastic-labs/honcho.git ${Volumes_Path}/honcho/source +# cp env.cfg.example env.cfg && $EDITOR env.cfg # 填入密码/API Key +# +# pull:: docker compose --env-file ./honcho/env.cfg -f ./honcho/stack.yml pull +# RUN:: docker compose -p honcho --env-file ./honcho/env.cfg -f ./honcho/stack.yml up -d --build +# disc:: +# - api/deriver 从 ${Volumes_Path}/honcho/source 源码 build（不是运行时 bind） +# - DB/Redis 数据 bind 挂到 WSL/Linux 原生 ext4（不能放 /mnt/9P drvfs） +# - 端口 8000=API, 5432=PG, 6379=Redis，全部绑定 0.0.0.0 供 LAN 访问 +# - 必须设置 HONCHO_LLM_API_KEY（占位符会导致 deriver 反复重启） +# - deriver 不可省：没它消息能写但不会产生记忆 +# - PG 5432 与 hindsight/dbSer 撞车，通过 HONCHO_DB_PORT 区分 +# ============================================================ + +services: + api: + build: + context: ${Volumes_Path}/honcho/source + dockerfile: Dockerfile + container_name: honcho-api + restart: unless-stopped + entrypoint: ["sh", "docker/entrypoint.sh"] + depends_on: + database: + condition: service_healthy + redis: + condition: service_healthy + ports: + - "${HONCHO_API_PORT:-8000}:8000" + environment: + - TZ=Asia/Shanghai + - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:5432/${HONCHO_DB_NAME} + - CACHE_URL=redis://redis:6379/0?suppress=true + - CACHE_ENABLED=true + - LOG_LEVEL=${HONCHO_LOG_LEVEL:-INFO} + - NAMESPACE=${HONCHO_NAMESPACE:-honcho} + - EMBED_MESSAGES=${HONCHO_EMBED_MESSAGES:-true} + - EMBEDDING_MODEL_CONFIG__TRANSPORT=openai + - EMBEDDING_MODEL_CONFIG__MODEL=${HONCHO_EMBEDDING_MODEL:-text-embedding-3-small} + - DERIVER_MODEL_CONFIG__TRANSPORT=openai + - DERIVER_MODEL_CONFIG__MODEL=${HONCHO_DERIVER_MODEL:-gpt-4o-mini} + - DERIVER_WORKERS=${HONCHO_DERIVER_WORKERS:-1} + - LLM_OPENAI_API_KEY=${HONCHO_LLM_API_KEY:?set HONCHO_LLM_API_KEY} + - MODEL_CONFIG__OVERRIDES__BASE_URL=${HONCHO_LLM_BASE_URL:-https://api.openai.com/v1} + - AUTH_USE_AUTH=${HONCHO_AUTH_USE_AUTH:-false} + - VECTOR_STORE_TYPE=pgvector + - VECTOR_STORE_MIGRATED=false + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + healthcheck: + test: + - CMD + - /app/.venv/bin/python + - -c + - "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=2).read()" + interval: 10s + timeout: 5s + retries: 10 + start_period: 30s + networks: + - honcho-net + + deriver: + build: + context: ${Volumes_Path}/honcho/source + dockerfile: Dockerfile + container_name: honcho-deriver + restart: unless-stopped + entrypoint: ["/app/.venv/bin/python", "-m", "src.deriver"] + depends_on: + api: + condition: service_healthy + database: + condition: service_healthy + redis: + condition: service_healthy + environment: + - TZ=Asia/Shanghai + - DB_CONNECTION_URI=postgresql+psycopg://${HONCHO_DB_USER}:${HONCHO_DB_PASSWORD}@database:5432/${HONCHO_DB_NAME} + - CACHE_URL=redis://redis:6379/0?suppress=true + - CACHE_ENABLED=true + - NAMESPACE=${HONCHO_NAMESPACE:-honcho} + - DERIVER_MODEL_CONFIG__TRANSPORT=openai + - DERIVER_MODEL_CONFIG__MODEL=${HONCHO_DERIVER_MODEL:-gpt-4o-mini} + - DERIVER_WORKERS=${HONCHO_DERIVER_WORKERS:-1} + - LLM_OPENAI_API_KEY=${HONCHO_LLM_API_KEY:?set HONCHO_LLM_API_KEY} + - MODEL_CONFIG__OVERRIDES__BASE_URL=${HONCHO_LLM_BASE_URL:-https://api.openai.com/v1} + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + networks: + - honcho-net + + database: + image: ${HONCHO_DB_IMAGE:-pgvector/pgvector}:pg${HONCHO_DB_VERSION:-18} + container_name: honcho-database + restart: unless-stopped + command: ["postgres", "-c", "max_connections=200"] + environment: + - TZ=Asia/Shanghai + - POSTGRES_USER=${HONCHO_DB_USER} + - POSTGRES_PASSWORD=${HONCHO_DB_PASSWORD:?set HONCHO_DB_PASSWORD} + - POSTGRES_DB=${HONCHO_DB_NAME} + - POSTGRES_HOST_AUTH_METHOD=${POSTGRES_HOST_AUTH_METHOD:-scram-sha-256} + - POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale=C --auth-host=${POSTGRES_HOST_AUTH_METHOD:-scram-sha-256} + - PGDATA=/var/lib/postgresql/data/pgdata + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + - ${Volumes_Path}/pgdata:/var/lib/postgresql/data + ports: + - "${HONCHO_DB_PORT:-5432}:5432" + healthcheck: + test: + - CMD-SHELL + - pg_isready -U ${HONCHO_DB_USER} -d ${HONCHO_DB_NAME} + interval: 10s + timeout: 5s + retries: 10 + networks: + - honcho-net + + redis: + image: ${HONCHO_REDIS_IMAGE:-redis}:${HONCHO_REDIS_VERSION:-8} + container_name: honcho-redis + restart: unless-stopped + command: ["redis-server", "--save", "60", "1", "--appendonly", "yes"] + environment: + - TZ=Asia/Shanghai + volumes: + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + - ${Volumes_Path}/redis:/data + ports: + - "${HONCHO_REDIS_PORT:-6379}:6379" + healthcheck: + test: ["CMD-SHELL", "redis-cli ping"] + interval: 10s + timeout: 5s + retries: 5 + networks: + - honcho-net + +networks: + honcho-net: + driver: bridge \ No newline at end of file