OpenCode-Obsidian安全设计揭秘：本地端口、CORS白名单与base64项目目录机制

本文以 OpenCode-Obsidian 插件为对象，完整拆解这款 Obsidian AI 助手插件的安全设计。OpenCode-Obsidian 将 OpenCode AI 助手直接嵌入 Obsidian 侧边栏，其本地端口监听、CORS 白名单与 base64 项目目录编码三大机制，正是它安全性的核心所在。

它是什么：把 AI 助手装进笔记软件侧边栏

OpenCode-Obsidian 的工作原理可以概括为三步：

1. 插件在本地启动一个opencode serve服务进程（由 ServerManager 统一调度）；
2. 用 Obsidian 的 iframe 视图加载 OpenCode 的 Web 界面，直接嵌进侧边栏或主视图；
3. 客户端通过 REST API 管理会话、注入笔记上下文（OpenCodeClient）。

既然涉及"本地起一个 HTTP 服务 + 网页嵌入"，安全设计就绕不开三个问题：服务能被谁访问？哪些网页能调用它？笔记库路径怎么安全地传递？下面逐一揭秘。

本地端口：默认只监听 127.0.0.1 回环地址

打开 src/types.ts，插件的默认配置一目了然：

这意味着 OpenCode 服务只对当前这台电脑自己可见。你的笔记库通过 API 暴露的所有能力，天然被锁在回环网络里——这是整条安全链的第一道闸门。

插件还会在每次启动前做健康检查：ServerManager.checkServerHealth 以 2 秒超时轮询/global/health，避免误判"别人已占用的端口"为可用端口，防止意外连上他人服务。

CORS 白名单：只放行app://obsidian.md一个来源

CORS（跨域资源共享）是浏览器层面的第二道防线。插件启动服务时固定传入白名单参数，见 ServerManager.ts：

opencode serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md

app://obsidian.md是 Obsidian 应用内嵌网页视图的"来源标识（origin）"。加上这个参数后：

• 只有 Obsidian 自己加载的页面可以调用 OpenCode API；
• 同一台电脑上打开的其他网页（哪怕是恶意页面）发起跨域请求会被浏览器直接拦截；
• 本地回环 + CORS 白名单叠加，形成"网络层 + 浏览器层"的双重隔离。

⚠️ 如果你在设置中启用了Custom Command（自定义命令）模式，必须手动保留--cors app://obsidian.md，否则 OpenCode 界面将无法嵌入——官方文档 README 对此有明确说明，设置面板的占位符也内置了完整示例（SettingsTab.ts）。

base64 项目目录：优雅化解中文、emoji 路径的编码难题

插件需要把"笔记库（vault）目录"告诉服务，但它没有把它拼进查询参数，而是将整个路径base64 编码后作为 URL 路径段，见 ServerManager.getUrl：

http://127.0.0.1:14096/<base64(项目目录)>

这个设计有三个好处：

1. 零转义：base64 输出只含字母、数字和+/=，空格、中文、emoji、#等特殊字符都不会破坏 URL 结构；
2. Unicode 全覆盖：项目专门用中文、日文、emoji 路径写了测试用例（tests/ServerManager.test.ts），验证C:/用户/Notes、/home/ユーザー/ノート、/home/user/📁Notes等路径生成的 URL 都正确包含 base64 编码结果；
3. 双重传递：API 请求头里还会附带原始的x-opencode-directory头（OpenCodeClient.request），URL 负责定位界面、请求头负责精确定位目录，各司其职。

目录本身的取值逻辑也很克制：优先用户显式配置，否则回落到 vault 路径（main.ts getProjectDirectory），插件不越权读取其他目录。

更多细节：进程组隔离与"善后"机制

安全性不止于网络层，进程生命周期同样被精心处理：

• 进程组隔离：Unix 下子进程以detached模式创建独立进程组（PosixProcess.ts），停止时对整个进程组先SIGTERM优雅终止、2 秒不退再SIGKILL强制清理（PosixProcess.ts），不留僵尸进程；
• 退出即停服：Obsidian 退出时自动停止服务（main.ts），服务生命周期与笔记软件严格绑定，不会"残留"在后台；
• 启动前预检：路径模式下先校验可执行文件存在且可执行，ENOENT、"存在但不可执行"等错误都会给出明确提示，避免静默失败。

小结：一张表看懂三大安全机制

可以看到，OpenCode-Obsidian 没有引入复杂的鉴权体系，而是用"回环监听 + CORS 白名单 + 目录编码 + 进程生命周期管理"这套组合拳，以最小复杂度实现了"AI 服务只服务于你自己的笔记"这一目标。

💡 想动手验证？开发者可克隆源码本地构建：git clone https://gitcode.com/gh_mirrors/op/opencode-obsidian，然后在.obsidian/plugins/obsidian-opencode目录下执行bun install && bun run build即可。