Ignis 自托管 Obsidian Web 部署与运维笔记

适用目标:在 VPS、NAS、家用服务器或 1Panel 管理的 Docker 环境中部署 Ignis,让 Obsidian 以真正 Web App 的形式运行在浏览器里。
推荐入口:公网和局域网都使用同一个 HTTPS 域名,例如https://obsidian.example.com:38080/。
本文示例参考了我当前稳定运行的 1Panel + OpenResty + Docker Compose 结构。
1. 项目简介
Ignis 是一个自托管的 Obsidian Web 运行方案。它不是远程桌面、不是 VNC、不是把桌面程序投屏到浏览器,而是在浏览器中运行 Obsidian 客户端,并通过兼容层把 Obsidian 依赖的 Electron API 转换成浏览器和服务端可以处理的调用。
官方项目说明里对它的定位很清楚:Ignis 让 Obsidian 在标准浏览器中运行,同时 Vault 仍保存在你的服务器上;项目本身不分发 Obsidian,Docker 容器首次运行时会从 Obsidian 官方来源下载对应版本。
官方参考:
- GitHub:Nystik-gh/ignis
- 官方文档:Ignis Documentation
- Docker 部署文档:Deploy with Docker
- 远程访问说明:Remote access
- 认证说明:Authentication
- 更新说明:Updating
- Docker 镜像:nobbe/ignis
截至 2026-08-14 查看官方文档,当前文档页显示 Ignis v0.8.9,镜像为 nobbe/ignis,支持 amd64、arm64,绑定的 Obsidian 版本为 1.12.7。以后新部署前建议再看一次官方文档和 release。
2. 功能亮点
Ignis 的核心价值是把“本地优先”的 Obsidian 体验搬到浏览器:
- 在浏览器里运行接近原生的 Obsidian 界面。
- 支持 Markdown 编辑器、Canvas、Bases、命令面板、右键菜单、主题和 CSS snippets。
- 支持多数基于 Obsidian 插件 API 的社区插件。
- 支持多 Vault,每个
/vaults子目录可以作为一个 Vault。 - 支持浏览器多标签页,不同标签可以打开不同 Vault 或不同 Workspace。
- 支持文件上传、拖拽、下载,文件夹可打包下载。
- 支持小屏幕自动使用移动端 UI。
- 支持 WebSocket 在标签页之间同步状态和编辑变化。
- 可配合 Obsidian Sync 或
obsidian-headless实现同步。 - 可以自托管,笔记文件仍在自己的服务器目录里,备份和迁移路径清楚。
3. 适合谁用
适合:
- 想从公司电脑、临时电脑、平板、浏览器访问自己的 Obsidian。
- 不想在每台设备都安装和同步 Obsidian 客户端。
- 希望所有插件、主题、工作区、设置集中在一套服务端环境里。
- 已经有 1Panel、Docker、NAS、VPS、内网穿透或反向代理环境。
- 习惯把 Vault 当普通文件夹备份。
不太适合:
- 完全不想维护服务器。
- 希望所有 Obsidian 插件都 100% 兼容。
- 想把它公开给陌生人使用,却不加登录认证。
- 依赖大量需要 Node 原生模块、
child_process、本地系统调用的插件。
4. 优点总结
真正的 Web App
传统方式如果想在浏览器里用 Obsidian,常见方案是 Docker 里跑桌面环境,再通过 VNC/noVNC 访问。体验像“远程桌面窗口”,移动端和输入体验都不太好。Ignis 的优势是直接把 Obsidian 作为 Web App 跑在浏览器里,交互更自然。
数据仍是普通文件
Vault 在服务器上还是普通目录。你可以用 rsync、restic、Duplicati、快照、NAS 备份等常规方式保护数据,不被锁在某个数据库或私有格式里。
统一环境
插件、主题、工作区、配置集中在服务端,换设备只要打开浏览器。对经常切换设备的人来说,这比每台设备单独同步一套 .obsidian 配置更省心。
适合自托管体系
它非常适合放进 1Panel / Docker Compose / 反向代理体系里统一管理。和你现在的部署一样,入口由 OpenResty 管 HTTPS,Ignis 容器只作为内网后端。
可控的安全边界
通过反向代理可以加 HTTPS、Basic Auth、SSO、Cloudflare Access、Tailscale、WireGuard 等访问控制。只要边界设计好,比直接暴露一个明文 HTTP 容器安全得多。
5. 主要限制
没有内置登录
这是最重要的一点。Ignis 官方明确说明:Ignis 没有内置认证。任何能访问实例的人,都可能读取和修改 Vault 文件。
所以公网访问必须加一层认证:
- 反向代理 Basic Auth
- Authelia / Authentik / OAuth2 Proxy
- Cloudflare Access
- Tailscale / WireGuard VPN
- 至少限制 IP 或只在内网开放
需要 HTTPS 或安全上下文
除 http://localhost 外,浏览器很多 API 只有在安全上下文里才可用。局域网或公网访问时,建议走 HTTPS。只用 http://192.168.x.x:端口,可能导致剪贴板、文件、部分插件功能异常。
插件兼容不是 100%
大部分普通插件可以工作,但以下插件容易出问题:
- 依赖 Node 原生模块的插件。
- 调用
child_process的插件。 - 强依赖本机文件选择器或系统 API 的插件。
- 需要桌面 Electron 特性的插件。
升级要跟着 Ignis 节奏
Ignis 每个版本会固定适配一个已知可工作的 Obsidian 版本。不要手动强行升级 Obsidian 到最新,否则兼容层可能跟不上。
6. 推荐架构

推荐结构:
<code class="language-text">用户浏览器 -> https://obsidian.example.com:38080 -> 1Panel / OpenResty / Nginx / Caddy -> http://127.0.0.1:38081 -> Ignis 容器 8080 -> /vaults /data /obsidian-app </code>
关键原则:
- 公网只暴露 HTTPS 反代端口。
- Ignis 容器后端端口只绑定
127.0.0.1。 - Vault、data、Obsidian 缓存都要持久化。
- 不要把 Ignis 的 HTTP 端口直接暴露到公网。
7. 手动部署流程

8. 准备目录
以 1Panel 常用 Compose 目录为例:
<code class="language-bash"># 创建 Ignis 的 Compose 部署目录 sudo mkdir -p /opt/1panel/docker/compose/ignis cd /opt/1panel/docker/compose/ignis # vaults 保存 Obsidian 仓库,data 保存 Ignis 自身配置,patches 可放自定义补丁 sudo mkdir -p vaults data patches # 把目录属主改成容器运行用户;如果你的 PUID/PGID 不是 1000,需要同步修改 sudo chown -R 1000:1000 vaults data patches </code>
如果你的运行用户不是 1000:1000,先查:
<code class="language-bash"># 查看当前用户和用户组,后面用于设置 PUID / PGID id id -u id -g </code>
然后把 compose 里的 PUID、PGID 改成对应值。
9. 推荐 docker-compose.yml
推荐用“本机后端端口 + HTTPS 反代”的方式:
<code class="language-yaml">services:
ignis:
# Ignis 官方 Docker 镜像;latest 会跟随最新版本,保守部署可固定版本号
image: nobbe/ignis:latest
# 固定容器名,方便 docker logs / docker ps / 1Panel 中识别
container_name: ignis
# 容器异常退出或服务器重启后自动恢复
restart: unless-stopped
ports:
# 推荐只绑定到 127.0.0.1,让 OpenResty/Nginx/Caddy 负责公网 HTTPS 入口
# 格式:宿主机IP:宿主机端口:容器端口
- "127.0.0.1:38081:8080"
environment:
# 浏览器最终访问地址;如果用了自定义 HTTPS 端口,端口也要写进去
- DOMAIN=https://obsidian.example.com:38080
# 容器内写文件时使用的用户和用户组,需与宿主机目录权限匹配
- PUID=1000
- PGID=1000
# 如果容器首次启动需要走代理下载 Obsidian / GitHub 资源,再打开下面两行
# - HTTP_PROXY=http://PROXY_HOST:PROXY_PORT
# - HTTPS_PROXY=http://PROXY_HOST:PROXY_PORT
# 如果插件代理需要访问内网服务,可按需允许内网 IP 或网段
# - PROXY_ALLOW_PRIVATE_HOSTS=YOUR_SERVER_LAN_IP
volumes:
# Obsidian Vault 根目录;每个子目录可作为一个 Vault
- ./vaults:/vaults
# Ignis 运行状态、插件状态、服务端配置等
- ./data:/app/data
# 缓存 Obsidian Web 资源,避免每次重建容器都重新下载
- obsidian-app:/app/obsidian-app
volumes:
# Docker 命名卷,用于保存 Obsidian 应用资源缓存
obsidian-app:
</code>
说明:
127.0.0.1:38081:8080表示 Ignis 后端只给本机反代访问,局域网和公网都不能直接访问这个 HTTP 端口。DOMAIN要写最终浏览器访问地址,尤其是带自定义端口时要写完整,例如https://obsidian.example.com:38080。vaults保存 Obsidian 仓库。data保存 Ignis 状态、插件状态、同步配置。obsidian-app是 Docker volume,用于缓存下载的 Obsidian 资源,避免每次重建都重新下载。
10. 启动容器
<code class="language-bash"># 进入部署目录 cd /opt/1panel/docker/compose/ignis # 检查 compose 语法和变量展开是否正常 docker compose config # 后台启动或更新容器 docker compose up -d # 查看实时日志,首次启动会下载 Obsidian 和 obsidian-headless docker compose logs -f </code>
首次启动会下载 Obsidian 和 obsidian-headless,通常需要一两分钟。日志里看到类似下面内容,就说明服务起来了:
<code class="language-text">Server running on http://localhost:8080 Vault root: /vaults </code>
检查容器:
<code class="language-bash"># 查看容器状态和端口映射
docker ps --format "table {{.Names}}t{{.Status}}t{{.Ports}}"
</code>
推荐状态:
<code class="language-text">ignis Up ... 127.0.0.1:38081->8080/tcp </code>
本机后端测试:
<code class="language-bash"># 从服务器本机测试 Ignis 后端 HTTP 服务是否正常 curl -I http://127.0.0.1:38081/ </code>
能返回 200 OK 即可。
11. 1Panel / OpenResty 反向代理
11.1 创建网站
在 1Panel 中创建网站:
<code class="language-text">网站类型:反向代理 主域名:obsidian.example.com 代理地址:http://127.0.0.1:38081 </code>
如果你的 80/443 被封,而你想使用 https://obsidian.example.com:38080/,需要让 OpenResty 监听自定义 HTTPS 端口。
11.2 添加自定义 HTTPS 端口
1Panel 生成的网站配置通常在:
<code class="language-text">/opt/1panel/www/conf.d/obsidian.example.com.conf </code>
找到:
<code class="language-nginx">listen 443 ssl ; </code>
下面加一行:
<code class="language-nginx">listen 38080 ssl ; </code>
完整片段类似:
<code class="language-nginx">server {
# 可保留 80,用于证书续签或跳转;如果运营商封锁 80,此入口可能不可用
listen 80 ;
# 标准 HTTPS 端口;如果 443 被封,此入口可能不可用
listen 443 ssl ;
# 自定义 HTTPS 端口,适合 80/443 被封的家庭宽带或特殊网络环境
listen 38080 ssl ;
# 对外访问的域名,必须和证书域名一致
server_name obsidian.example.com;
# 1Panel 生成或上传的证书文件
ssl_certificate /www/sites/obsidian.example.com/ssl/fullchain.pem;
ssl_certificate_key /www/sites/obsidian.example.com/ssl/privkey.pem;
# 引入 1Panel 生成的反向代理规则
include /www/sites/obsidian.example.com/proxy/*.conf;
}
</code>
代理配置通常在:
<code class="language-text">/opt/1panel/www/sites/obsidian.example.com/proxy/root.conf </code>
推荐内容:
<code class="language-nginx">location ^~ / {
# 反代到 Ignis 后端;后端只监听 127.0.0.1,不直接暴露公网
proxy_pass http://127.0.0.1:38081;
# 保留原始域名,方便 Ignis 判断最终访问来源
proxy_set_header Host $host;
# 传递客户端真实 IP
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header REMOTE-HOST $remote_addr;
# 支持 WebSocket / 长连接,Obsidian Web 同步状态会用到
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
# 告诉后端当前外部访问协议和端口
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
# WebSocket 反代建议使用 HTTP/1.1
proxy_http_version 1.1;
}
</code>
检查并重载 OpenResty:
<code class="language-bash"># 检查 OpenResty / Nginx 配置语法 docker exec OpenResty nginx -t # 配置检查通过后重载,不需要重启整个 OpenResty 容器 docker exec OpenResty nginx -s reload </code>
检查监听:
<code class="language-bash"># 确认 38080 已由反代服务监听,38081 只绑定本机后端 ss -tlnp | grep -E ':(38080|38081)' </code>
推荐状态:
<code class="language-text">0.0.0.0:38080 openresty 127.0.0.1:38081 docker-proxy / ignis </code>
11.3 证书注意
如果 80/443 被运营商封锁,普通 HTTP 验证可能无法签发证书。建议用:
- DNS 验证签发证书。
- Cloudflare DNS API。
- 1Panel 支持的 DNS 账户。
- 手动上传证书。
证书必须匹配域名,不要用 https://YOUR_SERVER_LAN_IP:38080 当常用入口,否则证书会报域名不匹配。
12. 内外网访问与 DNS 分流

推荐统一入口:
<code class="language-text">https://obsidian.example.com:38080/ </code>
外网:
<code class="language-text">obsidian.example.com -> 公网 IP 公网 TCP 38080 -> 服务器 OpenResty 38080 </code>
局域网:
<code class="language-text">obsidian.example.com -> YOUR_SERVER_LAN_IP 浏览器直接访问内网服务器上的 OpenResty </code>
这样有几个好处:
- 内网不绕公网回流,速度更快。
- 浏览器访问的仍是域名,证书匹配。
- 内外网收藏夹、插件配置、
DOMAIN都不用改。
如果用爱快软路由,可以找类似功能:
<code class="language-text">DNS设置 / DNS代理 / 域名解析 / 静态DNS / Host 绑定 </code>
添加:
<code class="language-text">obsidian.example.com -> YOUR_SERVER_LAN_IP </code>
如果爱快当前版本没有域名劫持/静态 DNS 功能,也可以用:
- AdGuard Home
- SmartDNS
- OpenWrt DNSMasq
- Windows hosts
- Pi-hole
Windows 临时 hosts:
<code class="language-text">YOUR_SERVER_LAN_IP obsidian.example.com </code>
刷新 DNS:
<code class="language-powershell"># 清理 Windows 本地 DNS 缓存 ipconfig /flushdns # 查看当前域名在这台电脑上实际解析到了哪里 nslookup obsidian.example.com </code>
内网应返回:
<code class="language-text">YOUR_SERVER_LAN_IP </code>
13. 可分享的配置模板
下面是可公开分享的通用模板。部署时只需要把域名、端口、用户 ID、代理地址等占位符替换成自己的环境即可。
<code class="language-yaml">services:
ignis:
# Ignis 官方镜像
image: nobbe/ignis:latest
# 容器名称
container_name: ignis
# 自动重启策略
restart: unless-stopped
ports:
# 后端端口只绑定本机,公网入口交给 HTTPS 反向代理
- "127.0.0.1:38081:8080"
environment:
# 最终浏览器访问地址
- DOMAIN=https://obsidian.example.com:38080
# 宿主机目录权限对应的用户和用户组
- PUID=1000
- PGID=1000
# 可选:服务器需要代理下载资源时再启用
# - HTTP_PROXY=http://PROXY_HOST:PROXY_PORT
# - HTTPS_PROXY=http://PROXY_HOST:PROXY_PORT
# 可选:插件代理需要访问内网服务时再启用
# - PROXY_ALLOW_PRIVATE_HOSTS=YOUR_SERVER_LAN_IP
volumes:
# Obsidian 仓库根目录
- ./vaults:/vaults
# Ignis 服务端数据目录
- ./data:/app/data
# Obsidian 应用资源缓存
- obsidian-app:/app/obsidian-app
volumes:
# Docker 命名卷
obsidian-app:
</code>
分享笔记时建议只保留这种通用模板,不写真实域名、真实内网 IP、代理地址、证书路径、容器运行时间或自定义补丁路径。
14. 数据目录与备份

最重要的是 vaults/。它保存真正的 Obsidian 笔记文件。
建议备份:
<code class="language-text">/opt/1panel/docker/compose/ignis/docker-compose.yml /opt/1panel/docker/compose/ignis/vaults/ /opt/1panel/docker/compose/ignis/data/ /opt/1panel/www/conf.d/obsidian.example.com.conf /opt/1panel/www/sites/obsidian.example.com/proxy/root.conf </code>
如果使用 Docker volume obsidian-app,它只是缓存 Obsidian 应用资源,丢了也能重新下载,不是第一优先级。但如果网络不稳定,也可以备份。
简单备份命令:
<code class="language-bash"># 进入上一级 compose 目录 cd /opt/1panel/docker/compose # 把 ignis 整个部署目录打包,包含 compose、vaults、data 等 tar -czf ignis-backup-$(date +%F).tar.gz ignis </code>
OpenResty 站点配置另备:
<code class="language-bash"># 单独备份 OpenResty / 1Panel 站点配置 # 第一个路径是主站点配置,包含 listen 端口和证书引用 # 第二个路径是站点目录,包含 proxy 规则、日志、证书等 tar -czf ignis-openresty-site-$(date +%F).tar.gz /opt/1panel/www/conf.d/obsidian.example.com.conf /opt/1panel/www/sites/obsidian.example.com </code>
更稳的方式:
- Vault 用 restic / kopia / rsync 定时备份。
- 配置文件纳入 Git 或定期压缩。
- 升级前手动复制一份
.bak.日期。 - 重要 Vault 做快照前,尽量先停止容器或确认没有大量写入。
15. 升级方法
升级前先备份:
<code class="language-bash"># 升级前先进入 compose 根目录 cd /opt/1panel/docker/compose # 升级前打包当前 Ignis 部署目录,方便回退 tar -czf ignis-before-upgrade-$(date +%F).tar.gz ignis </code>
升级:
<code class="language-bash"># 进入 Ignis 部署目录 cd /opt/1panel/docker/compose/ignis # 拉取新镜像 docker compose pull # 用新镜像重建并后台启动 docker compose up -d # 观察启动日志,确认没有下载失败或兼容错误 docker compose logs -f </code>
检查:
<code class="language-bash"># 检查容器运行状态和端口映射
docker ps --format "table {{.Names}}t{{.Status}}t{{.Ports}}"
# 从服务器本机测试 HTTPS 反代入口是否能返回页面
curl -k -I https://127.0.0.1:38080/ -H "Host: obsidian.example.com"
</code>
注意:
- 官方说明每个 Ignis 版本会固定一个已知兼容的 Obsidian 版本。
- 不建议手动设置
OBSIDIAN_VERSION抢先升级,除非你愿意承担兼容风险。 - 1Panel 修改网站配置后,可能覆盖你手工加的
listen 38080 ssl ;,升级或编辑网站后要复查。
16. 离线或代理环境
首次启动需要下载 Obsidian 和 obsidian-headless。如果服务器无法访问外网:
方案 A:给容器代理
<code class="language-yaml">environment: # HTTP 请求代理,例如下载依赖或访问外部资源 - HTTP_PROXY=http://代理IP:端口 # HTTPS 请求代理,例如访问 GitHub 或 Obsidian 下载地址 - HTTPS_PROXY=http://代理IP:端口 </code>
如果插件代理需要访问某个内网服务,可加:
<code class="language-yaml">environment: # 只允许插件代理访问指定内网主机;不要随意放开整个内网 - PROXY_ALLOW_PRIVATE_HOSTS=YOUR_SERVER_LAN_IP </code>
具体是否需要要看你的插件需求。不要随便放开整个内网网段。
方案 B:离线安装 Obsidian 包
官方部署文档说明,可以预先下载 Obsidian .deb 包,然后挂载给容器,并通过 OBSIDIAN_PACKAGE 指定:
<code class="language-yaml">services:
ignis:
volumes:
# 把预下载的 Obsidian 安装包挂载到容器内,只读即可
- ./obsidian.deb:/packages/obsidian.deb:ro
environment:
# 指定容器使用这个本地安装包,避免启动时在线下载
- OBSIDIAN_PACKAGE=/packages/obsidian.deb
</code>
建议下载与当前 Ignis 版本适配的 Obsidian 版本。
17. 常见故障
https://域名:38080 不能打开,但 http://域名:38080 可以
说明 38080 直接打到了 Ignis 容器的 HTTP 服务,没有经过 HTTPS 反代。
推荐修法:
<code class="language-yaml">ports: # Docker 端口映射配置 # 把 Ignis HTTP 后端限制在本机,避免直接暴露公网 - "127.0.0.1:38081:8080" # 仅允许宿主机本机访问 38081,再由反向代理转发 </code>
然后让 OpenResty 监听:
<code class="language-nginx"># OpenResty/Nginx 对外提供 HTTPS listen 38080 ssl ; # 内部转发给本机上的 Ignis 后端 proxy_pass http://127.0.0.1:38081; </code>
38081 在局域网打不开
这是推荐状态。38081 应只绑定 127.0.0.1,给 OpenResty 内部使用,不应该给局域网直接访问。
用 https://YOUR_SERVER_LAN_IP:38080 有证书警告
正常。证书是签给域名的,不是签给内网 IP 的。请使用:
<code class="language-text">https://obsidian.example.com:38080/ </code>
局域网通过 DNS 分流把域名解析到服务器内网 IP。
插件打不开内网服务
如果插件通过 Ignis 的跨域代理访问内网地址,可能被私有地址保护拦截。按需设置:
<code class="language-yaml"># 仅按需放行具体内网主机给插件代理访问 - PROXY_ALLOW_PRIVATE_HOSTS=YOUR_SERVER_LAN_IP # 允许插件代理访问指定内网服务器 </code>
只放行需要访问的 IP,不要过度放开。
容器首次启动很慢
正常。首次会下载 Obsidian 和 obsidian-headless。查看:
<code class="language-bash">docker compose logs -f # 实时查看 Ignis 容器日志,观察下载、启动和报错信息 </code>
如果网络不通,配置代理或使用 OBSIDIAN_PACKAGE 离线包。
Vault 不显示
检查目录结构:
<code class="language-text">vaults/
MyVault/
.obsidian/
notes.md
</code>
每个 Vault 应是 /vaults 下的一个子目录。
检查权限:
<code class="language-bash">ls -la /opt/1panel/docker/compose/ignis/vaults # 查看 Vault 目录属主和权限 sudo chown -R 1000:1000 /opt/1panel/docker/compose/ignis/vaults # 把 Vault 目录属主改为容器运行用户 </code>
NFS / SMB / NAS 挂载异常
如果 Vault 在 NAS 上,注意:
- 容器内必须能看到目标路径。
- 软链接目标也必须挂进容器。
- 权限要匹配
PUID/PGID。 - 慢速文件系统可关注 Ignis 的写入合并设置。
OpenResty 提示重复 server_name
说明同一个域名在 1Panel 里可能建了重复站点或重复配置。只要当前端口能正常访问,不一定立刻影响,但长期建议清理重复站点配置,避免证书续签或端口监听时混淆。
18. 安全清单
上线前逐项检查:
- 使用 HTTPS,不用公网 HTTP。
- Ignis 后端端口只绑定
127.0.0.1。 - 公网入口加认证或至少限制访问来源。
- Vault 有定时备份。
- 反代配置有备份。
- DNS 分流已配置,内网访问不绕公网。
- 不把代理允许范围开得过大。
- 不在公共网络分享无认证 URL。
19. 最小复刻清单
在新 VPS 上手动复刻时,按这个顺序:
- 安装 Docker 和 Docker Compose。
- 创建
/opt/1panel/docker/compose/ignis。 - 创建
vaults/、data/。 - 写入推荐版
docker-compose.yml。 docker compose up -d。- 本机测试
curl -I http://127.0.0.1:38081/。 - 在 1Panel 创建反代站点。
- 配置证书和
listen 38080 ssl ;。 - OpenResty 反代到
http://127.0.0.1:38081。 - 外网测试
https://域名:38080/。 - 内网 DNS 分流到服务器内网 IP。
- 设置备份任务。
20. 一句话结论
Ignis 最适合的定位是:把 Obsidian 变成一套自己掌控的浏览器工作台。它的体验比远程桌面轻,数据比纯云服务可控,但安全边界必须自己设计好。推荐始终使用“HTTPS 反代入口 + 本机 HTTP 后端 + Vault 定期备份”的架构。
