运维记录

ASK 知识库——运维记录

本文件记录知识库安装、同步过程中遇到的各类问题及解决方案，供运维参考和 AI 助手恢复上下文使用。 最后更新：2026-06-08

---

脚本与文件结构

文件	用途
点击这里安装知识库.bat	Windows 安装入口（双击运行，调用 install.ps1）
install.ps1	Windows 主安装脚本（7步：预检→Git→Obsidian→克隆→注册vault→快捷方式→自动同步）
sync.ps1	Windows 同步脚本（自动冲突处理）
同步知识库.bat	Windows 手动同步入口
安装知识库(Mac).command	Mac 安装脚本（双击运行，首次需右键→打开授权）
sync.sh	Mac 同步脚本（可双击或由 launchd 后台调用）
同步知识库(Mac).command	Mac 手动同步入口

仓库地址：https://github.com/ASK-jialingxiao/ASK-knowledge-base.git

安装路径：

• Windows：D:\ASK知识库（D盘可用空间>5GB时）或 %USERPROFILE%\Documents\ASK知识库
• Mac：~/Documents/ASK知识库

⚠️ 路径中必须包含”知识库”二字，否则 vault 名为 ASK，与知识库内部链接中的 vault=ASK知识库 不匹配，导致插件报错。

---

安装前提条件（Step 0 预检）

同事安装前需完成以下三步，脚本会逐一提示：

1

注册 GitHub 账号

使用公司邮箱 xxx@askhealthasia.com
前往 github.com/signup 注册

2

完成邮箱验证

收到 GitHub 验证邮件后
点击 Verify email address

3

获取仓库访问权限

将 GitHub 用户名和注册邮箱发送给管理员，收到邀请邮件后点击 Accept invitation

---

已知问题与解法

安装配置

安装 问题 1 Clone 失败——Token 类型错误 ✅ 已解决

现象

脚本在 Step 3 克隆仓库时报 Clone failed，同事粘贴的 token 以 github_pat_ 开头。

原因

使用了 Fine-grained token（github_pat_ 开头）而非 Classic token（ghp_ 开头）。Fine-grained token 默认不授权任何仓库，必须手动指定目标仓库，操作复杂且容易遗漏权限。

解法

1. GitHub → 右上角头像 → Settings → Developer settings
2. Personal access tokens → Tokens (classic)（不是 Fine-grained tokens）
3. Generate new token (classic)
4. Expiration 选 No expiration，勾选 repo 整个大类
5. 生成后复制（以 ghp_ 开头）

⚠️ 截图中若 token 已暴露，需立即在 GitHub 上 Revoke 并重新生成。

脚本处理：install.ps1 已加入自动检测，粘贴 github_pat_ 开头的 token 会立即报错并给出引导。

安装 问题 2 Vault not found——vault 名不匹配 ✅ 已解决

现象

Obsidian 打开后点击 Smart Connections、Copilot 等功能，弹出 Vault not found 错误，URL 中显示 vault=ASK知识库。

原因

脚本早期版本将知识库安装在 D:\ASK，Obsidian 将 vault 名注册为 ASK；但知识库内部 Advanced URI 链接写的是 vault=ASK知识库，两者不一致。

解法（已装的同事）

1. Obsidian 左下角 → Manage vaults（保险箱图标）
2. 找到 ASK vault → 点 ··· → Rename vault
3. 改名为 ASK知识库
4. 重启 Obsidian

脚本处理：安装路径已更新为 D:\ASK知识库，新安装的同事不会遇到此问题。

安装 问题 3 Vault 安装后需要手动添加 ✅ 已解决

现象

脚本运行完成后，打开 Obsidian 仍需手动点击"Open folder as vault"添加知识库，自动注册不生效。

原因

脚本在启动 Obsidian 前写入 obsidian.json，但 Obsidian 首次启动时触发引导流程，可能覆盖预写的配置。

解法

脚本改为双重保障：

1. 仍写入 obsidian.json（对非首次安装有效）
2. Obsidian 启动 6 秒后，通过官方 URI scheme 推送仓库路径：obsidian://open?path=<编码路径>

Obsidian 收到 URI 后会自动识别并注册 vault，无需手动操作。

安装 问题 8 Mac 用户无法使用 .bat 文件 ✅ 已解决

现象

Mac 同事收到 .bat 文件后无法运行。

原因

.bat 是 Windows 专用格式，Mac 不支持。

解法

为 Mac 用户提供 .command 文件（bash 脚本，双击运行）：

• 安装：安装知识库(Mac).command（首次需右键 → 打开，完成系统授权）
• 同步：同步知识库(Mac).command

Mac 自动同步通过 launchd plist 实现（每 4 小时），等效于 Windows 任务计划程序。

同步冲突

同步 问题 4 同步时 .obsidian/graph.json 冲突 ✅ 已解决

现象

同步时提示 Pull failed (merge): CONFLICTS: .obsidian/graph.json:content

原因

graph.json 存储每个人的图谱视图配置，每次打开 Obsidian 都会被修改，多人共用同一份会频繁产生冲突。

解法

已将 .obsidian/graph.json 加入 .gitignore 并解除 Git 追踪。同步脚本遇到 .obsidian/ 目录下的冲突会自动解决（采用远端版本）。

遗留冲突的同事（已卡住无法 pull）执行：

git checkout --theirs .obsidian/graph.json
git add .obsidian/graph.json
git commit -m "resolve conflict"
git rm --cached .obsidian/graph.json
git pull

同步 问题 5 同步失败——无法连接 GitHub ✅ 已解决

现象

fatal: unable to access '...' Failed to connect to github.com port 443

原因

GitHub 被公司网络防火墙或运营商拦截（443 端口不通）。

解法

• 连接 VPN 后重试
• 或切换到手机热点
• 如系公司网络统一拦截，需联系 IT 开放 443 端口对 github.com 的访问

脚本已更新错误提示，明确指出网络问题和 VPN 建议。

同步 问题 6 同步时 Push 被拒——non-fast-forward ✅ 已解决

现象

[rejected] refs/heads/main:refs/heads/main (non-fast-forward)，提示本地落后于远端。

原因

Obsidian Git 插件在自动同步时先 push 再 pull，导致本地落后时 push 失败。

解法

手动执行 git pull 后再同步；或在 Obsidian Git 插件设置中将同步顺序改为 Pull before push（先拉后推）。

插件与界面

插件 问题 7 Smart Connections——Smart lookup 点击无反应 ✅ 已解决

现象

点击 Smart lookup 按钮没有任何反应，也没有报错。

原因

.smart-env/（本地向量索引）已排除在 Git 同步之外，每位用户需在本地单独建立索引。首次使用时插件在后台静默下载本地模型并建索引，无明显进度提示。

解法

2026-06-08 后安装的同事：.smart-env/ 已纳入 Git 同步，克隆后可直接使用。

此前已安装的同事（索引未同步）：

1. 点击左侧 Smart Connections 图标，打开侧边栏
2. Settings → Smart Connections → 点击 Force Re-process
3. 等待 5–15 分钟（首次建索引，取决于知识库大小）
4. 或运行一次同步脚本，拉取最新 .smart-env/ 后即可使用

界面 问题 9 首页"+ 新增"按钮点击没有反应 ✅ 已解决

现象

首页项目&档案区域的"+ 新增"书脊点击无反应。

原因

该元素是 <div>，没有 href 或 data-href，不可点击。

解法

改为 <a class="internal-link zhiku-book zhiku-book-ghost" data-href="Templates/项目概览模板">，点击后打开项目模板页面。

数据与隐私

隐私 问题 10 Copilot 对话记录被同步到共享仓库 ✅ 已解决

现象

同事与 Copilot 的对话保存后出现在 copilot/copilot-conversations/ 文件夹，并随 git 同步到所有人的电脑。

原因

Copilot 插件的 defaultSaveFolder = copilot/copilot-conversations，该文件夹未排除同步。

解法

在 .gitignore 中添加并解除追踪：

copilot/copilot-conversations/
copilot/projects/
copilot/memory/

保留同步的内容：copilot/custom-prompts/、copilot/system-prompts/（共享配置，所有人共用）。

隐私 问题 11 个人笔记被同步给所有同事 ✅ 已解决

现象

同事新建的笔记出现在共享仓库，被其他人看到。

原因

Obsidian 默认将新建笔记保存在根目录，未排除同步。

解法

1. 在 .gitignore 中加入 Personal/，该文件夹内容不再同步
2. 在 .obsidian/app.json 中设置新建笔记默认路径：

   "newFileLocation": "folder",
   "newFileFolderPath": "Personal"

注意：Personal/ 在每人本地独立，互不可见。若需将个人笔记移入公共知识库，手动拖拽到对应目录即可。

插件与配置同步

同步 问题 12 新安装的插件未自动同步给同事 ✅ 已解决

现象

管理员在 Obsidian 中安装了新插件（如 Notebook Navigator），同事同步后插件未出现，仍需手动去 Community plugins 搜索安装。

原因

Obsidian 安装插件时会在 .obsidian/plugins/插件名/ 下新建文件夹，Git 不会自动追踪新增目录，必须手动 git add 后才纳入同步。community-plugins.json（记录哪些插件被启用）虽然已在追踪范围内，但插件文件本体没有提交，同事拉取后文件不存在，插件无法运行。

解法

安装并启用新插件后，将插件文件夹和启用记录一起提交：

git add .obsidian/plugins/插件名/
git add .obsidian/community-plugins.json
git commit -m "新增 xxx 插件"
git push

同事下次同步后插件自动到位且处于启用状态，无需任何手动操作。

CSS snippet 同理：新增 snippet 后需同时提交 .obsidian/snippets/文件名.css 和 .obsidian/appearance.json，同事才能自动激活样式。

---

.gitignore 排除规则说明

路径	原因
Personal/	每人的本地私有笔记，互不可见；新建笔记默认存入此处
.obsidian/workspace.json	每人的标签页、面板布局不同
.obsidian/workspace-mobile.json	同上，移动端
.obsidian/graph.json	每人的图谱视图配置不同，频繁变动会产生冲突
.obsidian/cache	本地缓存，体积大且自动生成
.smart-env/	已排除 已纳入同步（2026-06-08），新同事安装后可直接使用 Smart lookup
.claude/	Claude Code 本地配置，不应共享
public/	Quartz 构建产物，由 Cloudflare Pages 在线构建

---

同步脚本自动处理逻辑（sync.ps1 / sync.sh）

1. 清理追踪：每次同步前自动移除 .obsidian/graph.json、workspace.json 等文件的 Git 追踪（幂等操作）
2. 冲突检测：若存在未解决冲突：
   • .obsidian/ 下的文件 → 自动采用远端版本并提交
   • 其他文件 → 报错提示联系管理员，不自动处理
3. 网络错误识别：识别 Could not connect / unable to access 等字样，输出”请检查网络/VPN”的明确提示
4. 路径兼容：自动探测 ASK知识库 和旧版 ASK 两种安装路径

---

常用管理员操作

推送更新给所有同事

提交后同事下次同步自动拉取

cd D:\ASK知识库
git add .
git commit -m "描述本次更新"
git push

清除同事的冲突卡住状态

在同事电脑上执行

git checkout --theirs .obsidian/graph.json
git add .obsidian/graph.json
git commit -m "resolve conflict"
git pull

查看哪些文件有冲突

列出所有未解决冲突文件

git diff --name-only --diff-filter=U

同步新安装的插件 / CSS snippet

安装后需手动 add 才纳入追踪

# 同步插件
git add .obsidian/plugins/插件名/
git add .obsidian/community-plugins.json
git commit -m "新增 xxx 插件"
git push
同步 CSS snippet
git add .obsidian/snippets/文件名.css
git add .obsidian/appearance.json
git commit -m “新增 xxx snippet”
git push