Git 当笔记仓库用 Markdown 知识库工具做个人 Wikicpolar 临时分享给团队查阅团队文档最烦人的地方不是没人写而是写完之后散在聊天记录、网盘、个人电脑里。今天要做的不是再造一个复杂知识库系统而是把一堆 Markdown 文档放进 Git 仓库本地写、本地预览、有变更记录需要团队临时验收时再用 cpolar 开一个 HTTPS 查阅入口。这套方案适合放技术文档、FAQ、部署变更记录、接口说明、排错手册。划重点这里分享的是“只读预览页面”不是把 Git 仓库、编辑器、管理端口直接暴露出去。1 什么是 Git Markdown 个人 WikiGit Markdown 个人 Wiki说白了就是把知识库当成一个普通代码仓库来管理。每一篇文档都是.md文件目录就是文档分类提交记录就是知识库的变更历史。今天如果有人改了部署步骤明天发现写错了可以直接看 Git diff也可以回滚到上一版。这类方案和 Obsidian 泛笔记不一样。本文不讲双链、卡片盒、图谱也不讲 RAG 知识库。我们的主线只有一个用 Git 管住 Markdown 文档再用本地 Web 预览给团队远程查阅验收。HelloGitHub 上收录的 Tolaria 就是这类思路的代表。它把每个知识库看成一个 Git 仓库Markdown 文件可以随时迁移也能用普通编辑器继续维护。你可以用 Tolaria 做本地知识库编辑也可以只用 VS Code、Git 和 MkDocs 搭一套更轻的查阅页面。这篇文章会按后一种方式演示因为它更通用Windows、macOS、Linux 都能照着做最后给团队看的也是浏览器页面。我个人更喜欢这种“文件在本地、记录在 Git、展示用网页”的组合。平时写文档没有平台负担团队要验收时也不用临时拉人进某个系统。哪怕后面换工具这些 Markdown 文件和 Git 历史还在不会被某个软件格式锁住。2 环境准备Git、Python 和 cpolar先准备三个东西Git 用来做版本记录Python MkDocs 用来把 Markdown 渲染成网页cpolar 用来把本机预览页面临时分享出去。建议不要在服务器根目录、用户主目录乱建知识库。新建一个单独目录后面排错和清理都轻松。mkdir -p ~/wiki-lab cd ~/wiki-lab git --version python3 --version如果git --version和python3 --version都能输出版本号就可以继续。这里别急着装一堆插件先把最小链路跑通Markdown 能写、Git 能提交、网页能打开。cpolar 的安装按系统选择。macOS 可以用 Homebrewbrew tap probezy/core brew install cpolar sudo cpolar service install sudo cpolar service startLinux / 树莓派 / 支持 systemd 的新式 Linux可以使用官方一键安装脚本curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash安装完成后打开本机控制台地址curl -s http://127.0.0.1:9200 || echo cpolar 服务未启动浏览器能打开http://127.0.0.1:9200说明 cpolar 本地服务已经起来。账号绑定可以在 Web UI 登录完成也可以在纯命令行环境里执行cpolar authtoken xxx手动绑定。提醒一句本文只用 cpolar 分享知识库预览页面不分享 SSH、数据库、Git 凭据、私有仓库 token也不开放任何管理后台。3 初始化本地 Markdown 知识库仓库现在开始建知识库。目录结构不要一上来设计得很复杂先按“文档、FAQ、变更记录”三类分开团队看起来就够清楚。cd ~/wiki-lab mkdir team-wiki cd team-wiki git init mkdir -p docs/guide docs/faq docs/changelog接着写首页。首页不是摆设它负责告诉团队这个知识库里有什么、怎么查、当前验收看哪几页。cat docs/index.md EOF # 团队技术 Wiki 这个知识库用于沉淀项目技术文档、常见问题和变更记录。 ## 快速入口 - [部署说明](guide/deploy.md) - [常见问题](faq/common.md) - [变更记录](changelog/release-log.md) ## 查阅规则 - 只放脱敏后的技术文档 - 不写服务器真实目录、账号、密码、token - 变更步骤更新后需要提交 Git 记录 EOF这里已经把安全边界写到首页了。别小看这几行团队临时验收时大家会直接照着页面理解这个知识库的用途。4 写入技术文档、FAQ 和变更记录知识库要好用核心不是页面漂亮而是内容分类稳定。技术文档写“怎么做”FAQ 写“卡住了怎么办”变更记录写“什么时候改过什么”。先写一份部署说明cat docs/guide/deploy.md EOF # 部署说明 ## 本地启动 进入项目目录后执行 bash python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python app.py服务启动后在本机访问http://127.0.0.1:8000操作提醒.env文件只保存在本地不提交到知识库仓库文档里只写变量名不写真实密钥服务器真实路径统一用/path/to/project示例替代 EOF再写 FAQ。FAQ 不要写成大段说明直接按问题组织读者找答案更快。 bash cat docs/faq/common.md EOF # 常见问题 ## 页面打不开先检查什么 按顺序检查三件事 1. 本地服务是否已经启动 2. 端口是否填成了预览服务端口 3. cpolar 在线隧道列表里是否有公网 HTTPS 地址 ## 能不能把仓库地址发给外部同事 不发仓库地址。验收阶段只提供只读预览页面验收结束关闭 cpolar 隧道。 ## 文档里能不能写真实 token 不能。token、密码、私有仓库访问凭据只放在团队正式密钥系统里不写进 Markdown 文档。 EOF最后写变更记录。这个文件不用很长但日期、动作、影响范围要写清楚。cat docs/changelog/release-log.md EOF # 变更记录 ## 2026-07-22 - 初始化团队技术 Wiki - 增加部署说明、常见问题和查阅规则 - 增加临时验收时的安全边界说明 EOF写完后提交一次 Git。这里不是为了形式感而是给知识库建立第一条可追踪的基线。git add docs git commit -m init team markdown wiki如果提交时报用户名邮箱缺失先在当前仓库配置git config user.name wiki-maintainer git config user.email wiki-maintainerexample.com git commit -m init team markdown wiki这里别填个人私密邮箱内部知识库用团队约定的维护人标识更合适。5 用 MkDocs 做本地 Web 查阅页面Markdown 文件直接发给团队也能看但体验很散。我们用 MkDocs 起一个本地 Web 预览页面让目录、搜索和跳转都在浏览器里完成。先创建 Python 虚拟环境并安装 MkDocscd ~/wiki-lab/team-wiki python3 -m venv .venv source .venv/bin/activate pip install mkdocs创建 MkDocs 配置文件cat mkdocs.yml EOF site_name: 团队技术 Wiki site_url: http://127.0.0.1:8000/ docs_dir: docs nav: - 首页: index.md - 部署说明: guide/deploy.md - 常见问题: faq/common.md - 变更记录: changelog/release-log.md EOF启动本地预览服务mkdocs serve -a 127.0.0.1:8000现在打开http://127.0.0.1:8000能看到首页、左侧导航和搜索框就说明本地 Wiki 预览已经跑通。这张图适合放本地 Wiki 首页截图。读者要看到的重点不是界面多漂亮而是 Markdown 文档已经被组织成可查阅的网站。如果页面打不开先看终端里mkdocs serve是否还在运行再检查端口是不是8000。如果你电脑上已有服务占用了 8000可以换成 8080mkdocs serve -a 127.0.0.1:8080换端口后后面的 cpolar 命令也要同步换成同一个端口。6 用 cpolar 临时分享 HTTPS 查阅入口本地预览确认没问题后再开放给团队远程查阅。注意顺序先本地验证再开公网入口。本地页面没跑通时就开隧道只会把排错范围放大。保持 MkDocs 运行在127.0.0.1:8000另开一个终端执行cpolar http 8000命令启动后终端会输出一个公网访问地址。也可以打开 cpolar Web UIhttp://127.0.0.1:9200在“状态 → 在线隧道列表”里查看当前 HTTP 隧道对应的公网地址。把 HTTPS 地址发给团队团队成员就能在浏览器里查阅这份 Wiki。这张图适合放 cpolar 在线隧道列表截图。图里只需要展示协议、本地端口和公网 HTTPS 地址账号信息、token、其他隧道地址都要打码。这里有几个安全提醒建议直接照做只分享mkdocs serve的预览页面不分享http://127.0.0.1:9200管理端口文档里只放脱敏内容不写真实服务器目录、账号、密码、token不把.git目录、私有仓库地址、部署密钥当成页面内容展示验收结束后在运行 cpolar 的终端按CtrlC关闭临时隧道如果团队访问公网地址时打不开按这个顺序查本机http://127.0.0.1:8000是否能打开cpolar http 8000是否还在运行cpolar Web UI 的在线隧道列表里是否有 HTTPS 地址团队访问的地址是否复制完整这一步不是为了把个人 Wiki 长期挂到公网而是给一次验收、一次远程查阅、一次跨办公室确认开一个短时入口。长期团队知识库要走正式权限体系、备份策略和审计流程。7 验收完怎么收尾临时分享结束后不要只关浏览器。正确收尾是关闭隧道、提交文档变更、检查敏感内容。先在运行 cpolar 的终端按CtrlC再提交本次知识库配置cd ~/wiki-lab/team-wiki git status git add docs mkdocs.yml git commit -m add wiki preview structure检查 Git 记录git log --oneline --max-count5如果团队在验收时提了修改意见就改 Markdown 文件再提交一条清晰的 commit。别把所有修改都堆成“update docs”后面追问题会很痛苦。推荐用这种提交信息git commit -am docs: clarify deployment faq敏感内容也要查一遍。下面这个命令可以做一次基础扫描grep -RniE token|password|secret|AKIA|BEGIN RSA|PRIVATE KEY docs || true查到结果后人工确认。变量名可以保留真实密钥、私有 token、服务器真实路径必须删掉后再提交。8 总结到这里我们已经把一个本地 Markdown 知识库跑成了可查阅的个人 Wiki文档存在 Git 仓库里技术说明、FAQ、变更记录各自归档本地用 MkDocs 预览团队验收时用 cpolar 临时拿到 HTTPS 查阅入口。关键步骤其实就三件事用 Git 管理 Markdown 文档让每次文档变更都有记录用 MkDocs 把本地文档渲染成浏览器能查的 Wiki 页面用 cpolar 只开放预览端口验收结束立即关闭隧道这套方案的好处是轻不强绑定某个云知识库不需要一开始就上复杂权限系统也不会把内部文档长期暴露在外面。等团队真的要长期共用再补正式登录权限、备份策略、密钥管理和审计流程比一开始就堆平台稳得多。
