Obsidian + Claude Code + cc-switch 云服务器部署文档

适用环境：云服务器 + Docker，目标通过浏览器远程使用 Obsidian，并集成 Claude Code。

架构

浏览器 → :3000 → KasmVNC → labwc(Wayland) → Obsidian(Electron)
                                              ↓
                                     Claude Code (DeepSeek API via cc-switch)

文件清单

project/
├── Dockerfile.obsidian          # 镜像构建
├── obsidian-launch.sh           # 修复 Wayland 弹窗黑屏（关键）
├── fix-nginx-timeout.sh         # 修复容器内 nginx WebSocket 超时（备用）
└── docker-compose.obsidian.yml  # 部署配置

---

1. 拉取基础镜像

docker pull linuxserver/obsidian:1.12.7

2. Dockerfile

FROM linuxserver/obsidian:1.12.7
​
# 替换为清华源（兼容 Debian/Ubuntu）
RUN if [ -f /etc/apt/sources.list.d/debian.sources ]; then \
        sed -i 's|http://deb.debian.org|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/debian.sources; \
    elif [ -f /etc/apt/sources.list ]; then \
        sed -i 's|http://.*archive.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list; \
        sed -i 's|http://.*security.ubuntu.com|https://mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list; \
    fi
​
# 安装依赖（xz-utils 用于解压 Node.js 二进制）
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        curl \
        ca-certificates \
        fonts-noto-cjk \
        xz-utils \
    && apt-get clean && \
    rm -rf /var/lib/apt/lists/*
​
# 安装 Node.js 20.x
RUN curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/v20.18.0/node-v20.18.0-linux-x64.tar.xz \
        -o /tmp/node.tar.xz && \
    tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 && \
    rm /tmp/node.tar.xz
​
# 安装 Claude Code 和 cc-switch
RUN npm config set registry https://registry.npmmirror.com && \
    npm install -g @anthropic-ai/claude-code @songhe/cc-switch
​
# 修复内部 nginx WebSocket 超时（备用，默认 60s → 3600s）
COPY fix-nginx-timeout.sh /custom-cont-init.d/fix-nginx-timeout.sh
RUN chmod +x /custom-cont-init.d/fix-nginx-timeout.sh

3. obsidian-launch.sh（关键）

默认启动脚本检测到 labwc 后自动给 Electron 加 --ozone-platform=wayland。这会导致 Obsidian 打开弹窗（设置、命令面板等）时 Wayland 窗口层次错乱，KasmVNC 捕获画面丢失 Obsidian 窗口，表现为点任何按钮就黑屏，只剩 KasmVNC 背景界面。

#!/bin/bash
# 覆盖 /usr/bin/obsidian，强制走 XWayland 而非原生 Wayland
​
BIN=/opt/obsidian/obsidian
​
exec ${BIN} \
  --no-sandbox \
  --disable-gpu-sandbox \
  --in-process-gpu \
  "$@" > /dev/null 2>&1

4. fix-nginx-timeout.sh（备用）

linuxserver/obsidian 容器内部有 nginx 转发 WebSocket 到 KasmVNC，默认 proxy_read_timeout=60s。如果部署后出现"1 分钟就断连"，就是这个超时导致。此脚本在容器初始化时通过 /custom-cont-init.d/ 把超时改大。

#!/bin/bash
set -e
for conf in /etc/nginx/nginx.conf \
            /etc/nginx/conf.d/*.conf \
            /etc/nginx/sites-enabled/* \
            /defaults/nginx/*.conf \
            /defaults/nginx/site-confs/*; do
    if [ -f "$conf" ]; then
        sed -i 's/proxy_read_timeout [0-9]\+[smhd]*/proxy_read_timeout 3600s/g' "$conf" 2>/dev/null || true
        sed -i 's/proxy_read_timeout [0-9]\+/proxy_read_timeout 3600s/g' "$conf" 2>/dev/null || true
    fi
done

5. docker-compose.obsidian.yml

version: "3.8"
​
services:
  obsidian:
    build:
      context: .
      dockerfile: Dockerfile.obsidian
    container_name: obsidian
    mem_limit: 4g
    memswap_limit: 4g
    cpus: "2.0"
    shm_size: "2gb"             # Electron 需要较大的共享内存
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - LC_ALL=zh_CN.UTF-8
      - LANG=zh_CN.UTF-8
      - TITLE=Obsidian
    ports:
      - "3000:3000"   # KasmVNC HTTP
      - "3001:3001"   # KasmVNC HTTPS
      - "8082:8082"   # Data WebSocket（必须暴露）
    volumes:
      - /user/xinshuo/project/Obsidian:/config
      - /user/xinshuo/project/obsidian-launch.sh:/usr/bin/obsidian:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 45s

6. 部署步骤

# 1. 上传所有文件到服务器 /user/xinshuo/project/
​
# 2. 加执行权限
chmod +x /user/xinshuo/project/obsidian-launch.sh
​
# 3. 构建并启动
cd /user/xinshuo/project
docker compose -f docker-compose.obsidian.yml up -d --build
​
# 4. 检查启动状态
docker logs obsidian --tail 30
docker ps   # 确认 STATUS 为 (healthy)

启动后访问 http://<服务器IP>:3000 |https://<服务器IP>:3001 即可进入 Obsidian。

---

7. 配置 cc-switch + Claude Code

进入容器：

docker exec -it obsidian bash

7.1 初始化配置目录

mkdir -p /config/.claude
echo '{}' > /config/.claude/settings.json

7.2 添加 API 配置

# 语法: ccs add <名称> <API地址> <API Key>
​
# DeepSeek 示例
ccs add deepseek-v4-pro https://api.deepseek.com/anthropic sk-你的key
​
# 切换到该配置
ccs switch deepseek-v4-pro

注意：cc-switch 写入的环境变量为 ANTHROPIC_AUTH_TOKEN，部分 Claude Code 版本需 ANTHROPIC_API_KEY。如遇认证失败，手动修正：

cat > /config/.claude/settings.json << 'EOF'
{
"env": {
 "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
 "ANTHROPIC_API_KEY": "sk-你的key"
}
}
EOF

7.3 验证连通性

claude --print "hello"
# 正常应输出回复内容

---

8. 修复文件权限

Obsidian 在容器内以用户 abc 运行，需确保它能读取 Claude Code 配置：

docker exec obsidian bash -c "
  chown -R abc:abc /config/.claude
  chmod -R 755 /config/.claude
  chmod 600 /config/.claude/settings.json
"

---

9. 安装 Claudian 插件

项目	内容
GitHub	YishenTu/claudian

1. 浏览器访问 Obsidian

2. Settings → Community Plugins → 关闭 Restricted mode

3. 从 Releases 下载最新版本

4. 解压到 vault 的 .obsidian/plugins/claudian/ 目录

5. 在 Obsidian 设置 → 社区插件中启用 Claudian

6. 打开 Claudian 设置，确认 Claude CLI Path 为 /usr/local/bin/claude

7. 按快捷键或侧边栏图标打开对话，测试

9.1 安装 Skills（技能包）

Skills 让 Claude 更好地理解和操作 Obsidian 特有的文件格式和工作流。

项目	内容
GitHub	kepano/obsidian-skills

# 在 vault 根目录执行
git clone https://github.com/kepano/obsidian-skills.git .claude/skills/

重启 Obsidian 或重新加载 Claudian 插件后生效。

Skill	功能
obsidian-markdown	创建和编辑 Obsidian 风格的 Markdown（Wiki-links、Callouts、Properties 等）
obsidian-bases	创建和编辑 Obsidian Bases（.base 文件），用于数据库视图
json-canvas	创建和编辑 JSON Canvas 文件（.canvas），用于可视化画布
obsidian-cli	通过命令行与 Obsidian vault 交互，支持插件开发调试
planning-with-files	Manus 风格的文件规划系统，用于复杂任务管理

---

问题与解决汇总

问题	现象	原因	解决方案
构建失败：xz not found	tar: xz: Cannot exec	基础镜像未安装 xz-utils	apt-get install xz-utils
1 分钟断连	访问 Obsidian 不到 1 分钟就无法连接	容器内 nginx proxy_read_timeout=60s	fix-nginx-timeout.sh 改为 3600s
点按钮黑屏	点设置/命令面板后画面变黑，只剩 KasmVNC 背景	--ozone-platform=wayland 导致 Electron 弹窗窗口层次错乱	覆盖启动脚本，走 XWayland
ccs 参数错误	error: unknown option '--api-key'	语法不对，ccs add 直接接三个位置参数	正确语法：ccs add <name> <url> <token>
ccs switch 失败	Claude config directory does not exist	~/.claude 目录不存在	mkdir -p 并写入空 JSON
DeepSeek URL 错误	用了 platform.deepseek.com	Anthropic 兼容端点在 /anthropic 子路径下	改为 api.deepseek.com/anthropic
认证变量名不对	cc-switch 写入 ANTHROPIC_AUTH_TOKEN 不生效	部分版本需 ANTHROPIC_API_KEY	手动改为 ANTHROPIC_API_KEY
端口 8082 未暴露	Data WebSocket 不通	KasmVNC 数据通道走独立端口 8082	docker-compose 加 8082:8082
权限问题	Claudian 无法读取 Claude Code 配置	容器内 Obsidian 以 abc 用户运行，配置属主为 root	chown -R abc:abc /config/.claude