🚀 使用 Docker Compose 部署 Obsidian 网页版

🚀 使用 Docker Compose 部署 Obsidian 网页版

Obsidian 是一款基于 Markdown 的知识管理工具和思维导图工具，它通过双向链接和关系图谱功能，帮助用户构建个人知识体系。通过 Docker Compose 部署网页版 Obsidian，您可以在任何有浏览器的设备上访问和管理笔记。

📝 项目简介

Obsidian 的核心特点是其本地优先的设计理念——笔记以标准 Markdown 文件形式存储在本地，确保数据完全由用户控制。它通过双向链接（笔记间相互连接）和关系图谱（可视化展示笔记联系）来模拟人脑的联想思维，帮助用户建立知识网络。

Obsidian 网页版的核心优势： - 跨平台访问：通过浏览器随时随地访问笔记，无需安装客户端 - 多设备同步：基于 Web 的技术栈天然支持多设备访问 - 协作可能：为团队协作和知识共享提供基础 - 统一环境：所有用户在一致的界面和环境中工作

🔧 部署前准备

系统环境要求 - 操作系统：支持 Linux、Windows、macOS - Docker 引擎：版本 20.10+ - Docker Compose：版本 2.0+ - 硬件资源： - 内存：至少 2GB - 存储空间：至少 2GB 可用空间（根据笔记库大小调整）

环境检查 1. 检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态

1. 检查 Docker 版本 bash docker --version

2. 创建部署目录

   mkdir -p /home/compose/obsidian && cd /home/compose/obsidian

⚙️ 配置 Docker Compose

准备配置文件 创建 docker-compose.yml 文件，内容基于您提供的配置进行优化：

#version: '3'
#version: '2'
services:
    linuxserver:
        # LinuxServer 维护的 Obsidian 镜像，集成 Web 访问功能
        image: 'lscr.io/linuxserver/obsidian:latest'
        container_name: obsidian-with-zh  # 容器名称，便于管理
        devices:
            - /dev/dri:/dev/dri  # 挂载 GPU 设备，启用硬件加速（可选，低配置设备建议保留）
        #security_opt:
            #- seccomp:unconfined
        shm_size: "1gb"  # 共享内存大小，提升界面流畅度
        environment:
            - PUID=1000  # 本地用户 ID（执行 `id -u` 查看，需与目录所有者一致）
            - PGID=1000  # 本地用户组 ID（执行 `id -g` 查看，与 PUID 对应）
            - TZ=Asia/Shanghai  # 时区，确保日志与笔记创建时间正确
            # 安装扩展包：universal-package-install 用于安装额外软件（此处用于安装中文字体）
            - 'DOCKER_MODS=linuxserver/mods:universal-package-install'
            - INSTALL_PACKAGES=fonts-noto-cjk  # 安装 noto 中文字体，解决中文乱码
            - LC_ALL=zh_CN.UTF-8  # 配置中文语言环境
            - CUSTOM_USER=user1  # 登录用户名（可自定义，如 obsidian）
            - PASSWORD=your_strong_password  # 登录密码（必须修改！默认 obsidian 不安全）
            - TITLE="obsidian-web"  # Web 界面标题（自定义，如“我的知识库”）
        ports:
            - '3100:3000'  # 主界面端口映射：主机 3100 → 容器 3000
            - '3101:3001'  # 辅助服务端口映射：主机 3101 → 容器 3001
        #network_mode: 'host'   #这个模式用不了，一直报错。
        volumes:
            #- '${PWD}/obdocker:/config'
            # 数据持久化：本地 ./obdocker → 容器 /config（存储笔记文件与配置）
            - './obdocker:/config'
        restart: always  # 容器退出后自动重启，保障服务稳定
        #restart: unless-stopped
        #privileged: true   
#特权=开

关键配置说明

1. 镜像选择：使用 lscr.io/linuxserver/obsidian:latest 镜像，这是 LinuxServer.io 维护的 Obsidian 网页版镜像

2. 中文支持配置：

3. INSTALL_PACKAGES=fonts-noto-cjk：安装中文字体，解决中文显示问题
4. LC_ALL=zh_CN.UTF-8：设置中文语言环境

5. 这些配置解决了网页版 Obsidian 常见的中文显示和输入问题

6. 端口映射：

7. 3100:3000：主 Web 界面访问端口

8. 3101:3001：辅助服务端口

9. 数据持久化：

10. ./obdocker:/config：Obsidian 配置和笔记数据目录

11. 安全配置：

12. PUID=1000 和 PGID=1000：以非 root 用户运行，增强安全性
13. PASSWORD=obsidian：设置访问密码

🚀 启动与验证

启动服务

docker compose up -d

验证服务状态 1. 检查容器运行状态 bash docker ps 应该看到 obsidian-with-zh 容器处于 Up 状态

1. 查看服务日志 bash docker compose logs -f

2. 访问 Web 界面 在浏览器中访问 http://你的服务器IP:3100

初始设置 - 使用配置文件中设置的用户名 (user1) 和密码 (obsidian) 登录 - 首次使用可能需要创建或指定笔记库 (Vault) 的位置

---

（2）访问 Obsidian Web 界面

1. 打开浏览器，输入 http://服务器IP:3100（如本地测试：http://localhost:3100，远程服务器：http://192.168.1.100:3100）；
2. 首次访问会显示登录界面，输入配置中的 CUSTOM_USER（如 user1）和 PASSWORD（自定义密码）；
3. 登录成功后进入 Obsidian 主界面，左侧为笔记库目录，右侧为编辑区，说明服务正常；
4. 验证中文显示：新建笔记，输入 “测试中文显示”，若字体正常（无乱码），说明中文字体安装成功。

---

🔌 基础配置与使用

笔记库管理 1. 创建新笔记库 - 登录后点击"Create new vault" - 输入笔记库名称，如 "MyNotes" - 选择存储路径（默认在 /config 目录下）

1. 使用现有笔记库
2. 如果您有现有的 Obsidian 笔记库，可以通过挂载卷的方式导入
3. 在 docker-compose.yml 中添加额外卷挂载：

     volumes:
       - './obdocker:/config'
       - '/path/to/your/existing/vault:/config/your-vault-name'

中文环境优化 1. 界面语言设置 - 进入 Settings → Appearance - 在 Language 中选择 "中文（简体）"

1. 字体显示确认
2. 检查中文字体是否正常显示
3. 如仍有问题，可尝试挂载自定义字体

插件安装与配置 1. 启用社区插件 - 进入 Settings → Community plugins - 关闭 "Restricted mode"，点击 "Browse" 浏览插件市场

1. 推荐插件
2. Calendar：日记和日程管理
3. Kanban：看板任务管理
4. Dataview：高级数据查询和展示

---

🔌 基础配置与使用2

Obsidian 核心功能是 “创建双链笔记”，Web 版操作与本地客户端类似，新手可从以下步骤入手：

1. 步骤 1：创建第一个笔记

1.点击左侧 “文件夹” 图标 → 右键 “Vault”（根目录）→ 选择 “New note”； 2.输入笔记名称（如 “我的第一篇笔记”），按回车创建； 3.在编辑区输入内容（支持 Markdown 语法）：

    # 标题
    这是一段正文，支持 **加粗**、*斜体*、`代码块`。

    ## 双链示例
    点击 [[测试笔记]] 可创建或链接到另一篇笔记。

4.内容会自动保存（本地 ./obdocker/vault 目录下会生成对应的 .md 文件）。

2. 步骤 2：使用双链功能（核心特色）

1. 在笔记中输入 [[ 触发双链搜索，输入已有笔记名称（如 “测试笔记”），选择后生成链接；
2. 点击链接，若笔记不存在，会自动创建新笔记；若已存在，直接跳转；
3. 查看关联笔记：在笔记右侧 “Backlinks” 面板中，可看到所有链接到当前笔记的内容，构建知识网络。

3. 步骤 3：本地同步（数据双向访问）

由于笔记文件存储在本地 ./obdocker/vault 目录，可直接用本地 Obsidian 客户端打开，实现 “Web 编辑 + 本地备份”：

1. 本地安装 Obsidian 客户端（下载地址）；
2. 打开客户端 → 点击 “打开现有的库” → 选择服务器上的 ./obdocker/vault 目录（若为远程服务器，需通过 Samba/NFS 共享目录到本地）；
3. 本地修改的内容会自动同步到 Web 版（因文件共享），反之亦然。

4. 步骤 4：界面个性化（中文适配优化）

1. 点击左下角 “设置” 图标（齿轮）→ “Appearance”；
2. 选择 “主题”（如 “Default light” 或 “Default dark”）；
3. 确认 “Font” 设置为 “Noto Sans”（中文字体），确保中文显示清晰。

---

🛠️ 维护与管理

日常维护操作 1.服务启停

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

2.数据备份

   # 备份 Obsidian 配置和笔记数据
   tar -czf obsidian-backup-$(date +%Y%m%d).tar.gz ./obdocker

3.服务更新

   # 进入部署目录
   cd /home/compose/obsidian

   # 拉取最新镜像并重启
   docker compose pull
   docker compose down
   docker compose up -d

监控与日志 1.查看实时日志

   docker compose logs -f

2.监控资源使用

   docker stats obsidian-with-zh

🐛 常见问题排查

1. 无法访问 Web 界面 - 问题现象：浏览器访问 http://IP:3100 无响应 - 解决方案： - 检查防火墙设置，确保 3100 端口已开放 - 验证容器状态：docker ps - 查看服务日志：docker compose logs

2. 中文显示异常 - 问题现象：中文显示为方块或乱码 - 解决方案： - 确认 fonts-noto-cjk 包正确安装 - 检查 LC_ALL=zh_CN.UTF-8 环境变量设置 - 重启容器应用字体更改

3. 中文输入问题 - 问题现象：无法输入中文 - 解决方案： - 这是网页版 Obsidian 的已知问题 - 可尝试使用浏览器自带的输入法支持 - 或考虑使用桌面客户端进行内容录入，通过文件同步更新

4. 文件同步方案 虽然网页版 Obsidian 提供了便捷的访问方式，但对于多设备间的笔记同步，可以考虑以下方案：

• 自建同步服务器：使用 CouchDB 配合 LiveSync 插件搭建私有同步服务
• Git 同步：通过 Git 仓库管理笔记版本和同步
• 云存储同步：使用 Nextcloud 或其他 WebDAV 服务进行文件同步

通过本教程，您应该已经成功部署并配置了 Obsidian 网页版服务。Obsidian 的强大知识管理功能结合网页版的便捷访问，将为您提供一个高效的知识组织和协作平台。如果在使用过程中遇到其他问题，可以参考 Obsidian 官方文档或相关社区资源。

---

🐛 常见问题排查2

1. 中文显示乱码（方块或空白）

• 原因 1：中文字体未安装成功（INSTALL_PACKAGES=fonts-noto-cjk 配置未生效）。解决：

  1. 查看容器日志确认字体安装：docker compose logs | grep "fonts-noto-cjk"，若显示 “installed” 则正常；
  2. 若未安装，重启容器：docker compose restart，重新触发安装；
  3. 仍失败则进入容器手动安装：docker exec -it obsidian-with-zh apt update && apt install -y fonts-noto-cjk。
  4. 原因 2：语言环境未配置（LC_ALL=zh_CN.UTF-8 未生效）。解决：进入容器验证语言环境：docker exec -it obsidian-with-zh locale，若输出 LC_ALL=zh_CN.UTF-8 则正常，否则检查 docker-compose.yml 配置是否正确。

2. 无法登录（提示 “用户名或密码错误”）

• 原因 1：输入的用户名 / 密码与 CUSTOM_USER/PASSWORD 不一致。解决：确认配置中的用户名和密码，注意区分大小写（如 User1 与 user1 不同）。

• 原因 2：密码包含特殊字符（如 $ &），Docker Compose 解析错误。解决：将密码用单引号包裹（如 PASSWORD='Obsidian$2024!'），重启容器。

3. 笔记无法保存（提示 “权限不足”）

• 原因：./obdocker 目录权限不足，容器无法写入文件。

  解决：重新赋予权限：sudo chmod -R 777 ./obdocker，重启容器后测试保存。

4. Web 界面卡顿或加载缓慢

• 原因 1：服务器内存不足（shm_size 配置不足）。解决：修改 shm_size: "2gb"（增加共享内存），重启容器：docker compose up -d。

• 原因 2：网络延迟（远程访问时）。解决：确保服务器带宽充足，或通过本地客户端访问（利用文件共享）。

5. 容器启动后立即退出（无明显错误日志）

• 原因：PUID/PGID 与目录所有者 ID 不匹配，导致容器初始化失败。

  解决： 1. 查看本地用户 ID：id -u（如输出 1002）； 2. 修改 docker-compose.yml 中的 PUID=1002 和 PGID=1002（与用户组 ID 一致）； 3. 重启容器：docker compose up -d。

通过以上步骤，新手可快速搭建带中文支持的 Web 版 Obsidian，实现跨设备笔记管理与知识构建。Obsidian 双链功能适合深度思考与知识关联，后续可探索插件（如思维导图、表格）扩展功能，具体可参考 Obsidian 官方文档。