Obsidian 全库 MkDocs GitHub 上线方案¶

这份记录是按当前基础设施写的一版可直接照做的最终方案。

当前结论：

把整个 D:\Obsidian 作为发布素材源
使用 Portainer 的 Repository / GitOps 模式部署
由 Dockerfile + mkdocs.yml 在仓库内直接构建镜像
主同步通道走 GitHub
在线修改先走 GitHub Web 或 github.dev
接入 proxy-kr
由 Traefik-KR 反向代理
不额外暴露公网 ports
不需要额外的 builder 轮询容器
mkdocs.yml 和 Dockerfile 都直接跟仓库一起走

1. 仓库内文件¶

当前这套方案直接依赖仓库根目录这两个文件：

其中：

mkdocs.yml 负责把整个 Vault 当成素材源构建站点
Dockerfile 负责在镜像构建阶段执行 mkdocs build
最终镜像直接内置构建好的静态站点

2. Portainer Stack¶

在 Portainer 中新建 Stack，名称建议为 app-obsidian-docs，选择：

Build method: Repository
仓库指向当前 Obsidian 仓库
Compose 路径指向： app-obsidian-docs.yml

Stack 内容如下：

services:
  app-obsidian-docs:
    build:
      context: .
      dockerfile: Dockerfile
    image: app-obsidian-docs:latest
    container_name: app-obsidian-docs
    restart: unless-stopped
    networks:
      - proxy-kr
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app-obsidian-docs.rule=Host(`docs.120224.xyz`)"
      - "traefik.http.routers.app-obsidian-docs.entrypoints=websecure"
      - "traefik.http.routers.app-obsidian-docs.tls.certresolver=letsencrypt"
      - "traefik.http.services.app-obsidian-docs.loadbalancer.server.port=80"

networks:
  proxy-kr:
    external: true
    name: ${NETWORK_NAME}

3. Portainer 环境变量¶

在 Stack 的 Environment variables 中添加：

NETWORK_NAME=proxy-kr

4. 首次访问¶

如果配置正确，浏览器访问：

https://docs.120224.xyz

应该可以直接打开站点。

5. GitHub 同步方式¶

这次主同步通道直接用 GitHub + Portainer GitOps。

平时可以：

本地改完后 git push
直接在 GitHub 网页上改 .md
或者用 github.dev

然后由 Portainer 的仓库更新机制重新拉取并重建镜像。

6. 这次实际要注意的点¶

不要把 `.obsidian` 和缓存内容一起发出去¶

这些目录是本地工作区状态，不是文档内容本身，应该在 mkdocs.yml 里排除。

这次不需要额外的同步 builder 容器¶

Portainer 既然已经用 Repository 模式拉仓库，就不该再在业务容器里自己写一套轮询 Git。

当前镜像构建职责已经收敛为：

Portainer 拉仓库
Docker 根据 Dockerfile 构建
MkDocs 在镜像构建阶段产出静态站点
nginx 直接提供页面

不要把这个站点做成“只发 20_服务器”¶

这次目标就是整个 D:\Obsidian，所以仓库根目录里的 mkdocs.yml 直接以整库为素材源。

`MkDocs` 不会天然兼容所有 Obsidian 双链¶

第一版先保证能稳定浏览和搜索。

如果后面遇到 [[...]] 链接异常，再单独补兼容层，不要在第一步把事情做复杂。

私有仓库要额外处理认证¶

如果仓库不是公开仓库，需要按 Portainer 的 Repository 认证方式配置访问凭据。

7. 最终确认项¶

跑通后的关键状态应该是：

app-obsidian-docs 容器为 running
浏览器访问 https://docs.120224.xyz 能打开站点
整个 Vault 的 Markdown 目录能正常浏览
本地 git push 后，Portainer 重新部署后能刷新站点
临时在 GitHub Web 修改 Markdown 后也能同步生效