企业官网建设流程全解析

Git 当笔记仓库？用 Markdown 知识库工具做个人 Wiki，cpolar 临时分享给团队查阅

团队文档最烦人的地方，不是没人写，而是写完之后散在聊天记录、网盘、个人电脑里。今天要做的不是再造一个复杂知识库系统，而是把一堆 Markdown 文档放进 Git 仓库：本地写、本地预览、有变更记录，需要团队临时验收时，再用 cpolar 开一个 HTTPS 查阅入口。

这套方案适合放技术文档、FAQ、部署变更记录、接口说明、排错手册。划重点：这里分享的是“只读预览页面”，不是把 Git 仓库、编辑器、管理端口直接暴露出去。

1 什么是 Git + Markdown 个人 Wiki？

Git + 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 可以用 Homebrew：

brew tap probezy/core && brew install cpolar sudo cpolar service install sudo cpolar service start

Linux / 树莓派 / 支持 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-maintainer@example.com" git commit -m "init team markdown wiki"

这里别填个人私密邮箱，内部知识库用团队约定的维护人标识更合适。

5 用 MkDocs 做本地 Web 查阅页面

Markdown 文件直接发给团队也能看，但体验很散。我们用 MkDocs 起一个本地 Web 预览页面，让目录、搜索和跳转都在浏览器里完成。

先创建 Python 虚拟环境并安装 MkDocs：

cd ~/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，可以换成 8080：

mkdocs serve -a 127.0.0.1:8080

换端口后，后面的 cpolar 命令也要同步换成同一个端口。

6 用 cpolar 临时分享 HTTPS 查阅入口

本地预览确认没问题后，再开放给团队远程查阅。注意顺序：先本地验证，再开公网入口。本地页面没跑通时就开隧道，只会把排错范围放大。

保持 MkDocs 运行在127.0.0.1:8000，另开一个终端执行：

cpolar http 8000

命令启动后，终端会输出一个公网访问地址。也可以打开 cpolar Web UI：

http://127.0.0.1:9200

在“状态 → 在线隧道列表”里查看当前 HTTP 隧道对应的公网地址。把 HTTPS 地址发给团队，团队成员就能在浏览器里查阅这份 Wiki。

这张图适合放 cpolar 在线隧道列表截图。图里只需要展示协议、本地端口和公网 HTTPS 地址，账号信息、token、其他隧道地址都要打码。

这里有几个安全提醒，建议直接照做：

• 只分享mkdocs serve的预览页面，不分享http://127.0.0.1:9200管理端口
• 文档里只放脱敏内容，不写真实服务器目录、账号、密码、token
• 不把.git目录、私有仓库地址、部署密钥当成页面内容展示
• 验收结束后，在运行 cpolar 的终端按Ctrl+C关闭临时隧道

如果团队访问公网地址时打不开，按这个顺序查：

1. 本机http://127.0.0.1:8000是否能打开
2. cpolar http 8000是否还在运行
3. cpolar Web UI 的在线隧道列表里是否有 HTTPS 地址
4. 团队访问的地址是否复制完整

这一步不是为了把个人 Wiki 长期挂到公网，而是给一次验收、一次远程查阅、一次跨办公室确认开一个短时入口。长期团队知识库要走正式权限体系、备份策略和审计流程。

7 验收完怎么收尾

临时分享结束后，不要只关浏览器。正确收尾是：关闭隧道、提交文档变更、检查敏感内容。

先在运行 cpolar 的终端按：

Ctrl+C

再提交本次知识库配置：

cd ~/wiki-lab/team-wiki git status git add docs mkdocs.yml git commit -m "add wiki preview structure"

检查 Git 记录：

git log --oneline --max-count=5

如果团队在验收时提了修改意见，就改 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 只开放预览端口，验收结束立即关闭隧道

这套方案的好处是轻：不强绑定某个云知识库，不需要一开始就上复杂权限系统，也不会把内部文档长期暴露在外面。等团队真的要长期共用，再补正式登录权限、备份策略、密钥管理和审计流程，比一开始就堆平台稳得多。