你Obsidian里攒了好几年的笔记，是不是除了自己偶尔翻翻，基本在吃灰？

我也是。直到我把整个 vault 挂进了一个本地 AI 网关，现在它能直接在我的笔记里检索、帮我起草文档，而且数据一步都不出内网。

这件事听起来像一句话就能搞定，实际部署的时候，CouchDB 不手动建库直接报错，挂载目录权限不对就 Permission denied，中文笔记在容器里还可能变成方块。我前后折腾了两轮才跑顺。

今天把完整的部署方案拆开讲清楚：CouchDB、Obsidian 远程版、Hermes 网关三个服务，用一个 docker-compose.yml 一把跑通，文末附上我实打实踩过的三个坑。你照着抄，能省掉我那两轮的弯路。

为什么是这三个组件

先说清楚各自干啥，不然后面配环境变量的时候你会一脸懵。

类别	名称	版本	镜像/程序
智能体	Hermes	v2026.7.20	nousresearch/hermes-agent:v2026.7.20
文档数据库	CouchDB	3.4.2	apache/couchdb:3.4.2
知识库（Web）	Obsidian	v1.7.7	sytone/obsidian-remote:latest
知识库（桌面）	Obsidian	v1.13.4	Obsidian-1.13.4.exe
同步插件	Self-hosted LiveSync	v1.0.11	Self-hosted LiveSync

一句话分工：Obsidian 存你的笔记本体，CouchDB 当 RAG 的向量和元数据存储，Hermes 是那个能读 vault、能基于你的笔记回答问题的智能体网关。桌面端 Obsidian 装个 LiveSync 插件，把笔记同步进容器挂载的目录就行。

端口规划如下，Hermes 的 8642 是 Gateway API 端口，9119 是 Web 管理面板端口。

组件	IP	对内端口	对外端口
Hermes	192.168.10.110	8642	9119
CouchDB	192.168.10.110	5984	5984
Obsidian	192.168.10.110	8080	8080

先把目录建好

挂载路径都基于同一个工作目录，先建出来，后面 docker-compose 里的卷映射才不会飘。

mkdir -p hermes-deploy/data/agent
mkdir -p hermes-deploy/agent
mkdir -p hermes-deploy/config
mkdir -p hermes-deploy/vaults
mkdir -p hermes-deploy/fonts
cd hermes-deploy

五个目录各管一摊事：

• • data/agent 存放 Hermes 运行数据

• • agent 映射容器的 /root/.hermes，存配置

• • config 放 CouchDB 和 Obsidian 的配置

• • vaults 放 Obsidian 知识库本体，也是桌面端同步的目标

• • fonts 放中文字体

docker-compose.yml 全量贴出

三个服务放在同一个文件里，下面这段可以直接整段抄走。

version: '3.8'

services:
  # 1. CouchDB，作为 RAG 的向量/元数据存储
  couchdb:
    image: apache/couchdb:3.4.2
    container_name: obsidian-couchdb
    restart: unless-stopped
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=admin123.com
      - CLUSTER_SIZE=1
    volumes:
      - ./data:/opt/couchdb/data
      - ./config:/opt/couchdb/etc/local.d

  # 2. Obsidian 远程访问（Web 端）
  obsidian-remote:
    image: sytone/obsidian-remote:latest
    container_name: obsidian-remote
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config:/config
      - ./vaults:/vaults
      - ./fonts:/usr/share/fonts/truetype/custom
    environment:
      - PUID=10000
      - PGID=10000
      - TZ=Asia/Shanghai
      - DOCKER_MODS=linuxserver/mods:universal-package-install
      - INSTALL_PACKAGES=fonts-wqy-zenhei fonts-wqy-microhei

  # 3. Hermes 智能体网关
  hermes-gateway:
    image: nousresearch/hermes-agent:v2026.7.20
    container_name: hermes-gateway
    restart: unless-stopped
    ports:
      - "8642:8642"   # Gateway API 端口
      - "9119:9119"   # Web 管理端口
    environment:
      - TZ=Asia/Shanghai
      - HERMES_ALLOW_ROOT_GATEWAY=1
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_HOST=0.0.0.0
      - HERMES_DASHBOARD_PORT=9119
      - HERMES_DASHBOARD_INSECURE=1
      - HOME=/opt/data
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=admin123.com
      # 解决警告的配置
      - GATEWAY_ALLOW_ALL_USERS=true   # 测试环境开放所有用户，生产环境改成白名单
      # CouchDB 连接配置
      - VECTOR_DB_URL=http://couchdb:5984
      - VECTOR_DB_USER=admin
      - VECTOR_DB_PASS=admin123.com
      # Obsidian 挂载路径
      - OBSIDIAN_VAULT_PATH=/obsidian/jiandaoyun
    volumes:
      - ./data/agent:/opt/data
      - ./agent:/root/.hermes
      # 关键，把本地 Obsidian 库挂载到容器内
      - ./vaults:/obsidian/jiandaoyun
    command: gateway run   # 关键，必须指定启动命令

几个关键点单独拎出来说：

HOME=/opt/data 把数据目录指到挂载卷，配置目录通过 ./agent:/root/.hermes 映射出来，容器删了配置还在。

GATEWAY_ALLOW_ALL_USERS=true 只在测试环境用，上生产前务必换成白名单，否则谁都能调你的网关。

Obsidian 这边通过 DOCKER_MODS 装了文泉驿正黑和微米黑。这步不能省，否则容器里的中文笔记会显示成方块，你检索到的内容全是乱码。

一条命令启动

docker-compose up -d

起来以后看一眼三个容器的状态：

docker-compose ps

都 Up 了就往下走。CouchDB 还有个初始化步骤，放到避坑指南里讲，别急着关页面。

验证：让 AI 真正读到你笔记

光起服务不算通，得确认 Hermes 能读写你的 vault。直接在对话里下两条自然语言指令就行。

先让它把 vault 里的 Markdown 笔记全列出来：

列出我的 Obsidian vault 里所有的 Markdown 笔记

再让它写一条，看能不能落盘：

写入我的 Obsidian vault 里一条 Markdown 笔记 标题：你是Openclaw 内容：你是Obsidian知识库

读得到、写得出，说明挂载路径和 vault 都通了，RAG 检索这条线也就接上了。到这一步，你就可以问它“我那篇讲 VNC 的笔记里端口是多少”之类的问题，它会基于你的笔记答。

三个坑，我一个没躲过

这套东西的坑都是实际部署时踩出来的，按踩中的顺序讲。

坑一：挂载目录 Permission denied

Docker 挂载的 Obsidian 目录，容器内用户必须有权限读写。我第一次跑，列表笔记直接报 Permission denied。

解决办法，在对应服务的 docker-compose.yml 里加一行：

user: "1000:1000"

坑二：Front Matter 打架

用 MinerU 这类工具把 PDF 解析进 Obsidian 时，生成的内容可能自带 ---，会干扰 Obsidian 的属性解析，笔记直接显示异常。

在 Hermes 里开这个开关就好：

sanitize_frontmatter: true

坑三：CouchDB 不建库直接报错（最容易被漏）

这是我最想提醒你的一步。首次启动后 CouchDB 不会自动建库，你得手动访问 http://localhost:5984/_utils，创建 _users 和 hermes_vectors 两个数据库，否则 RAG 一上来就报错。

我第一次就是没建库，对着报错查了半个钟头，以为镜像有问题。建议 docker-compose up -d 之后第一件事就把它做了。

上线前必改的两处配置

admin123.com 这个密码和 GATEWAY_ALLOW_ALL_USERS=true 都是测试配置，写进文章方便你抄，但你上生产环境之前记得换掉：密码改成强的，网关改成白名单。

写在最后

整套东西的分工是 CouchDB 存数据、Obsidian 管笔记、LiveSync 同步桌面端、Hermes 挂载 vault 做检索。部署时盯住三个坑：权限、Front Matter、CouchDB 建库，基本就不会卡住。