运维记录

ASK 知识库——运维记录

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

---

脚本与文件结构

文件	用途
点击这里安装知识库.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知识库

Git 安装路径：D盘可用空间>1GB时安装到 D:\Git，否则使用 Git 默认路径（C盘）。Obsidian 因其自动更新机制（Squirrel）固定安装在 %LOCALAPPDATA%\Obsidian（C盘），无法更改。

⚠️ 路径中必须包含”知识库”二字，否则 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，无需手动操作。

安装 问题 13 Clone 失败——传输中断 / 完全连不上 GitHub ✅ 已解决

现象

Step 3 克隆时出现两类报错：

1. Failed to connect to github.com port 443 ... Could not connect to server（完全连不上）
2. RPC failed; curl 56 schannel: server closed abruptly (missing close_notify) / unexpected disconnect while reading sideband packet / fatal: early EOF（连上但传输中断）

两者均出现在网页版 GitHub 可正常打开的情况下。

原因

第1类是网络层面无法建立连接，常见于公司代理配置只对浏览器生效、杀毒软件/防火墙拦截 git.exe 进程、VPN分流等。第2类是连接建立后被中断，常见于网络不稳定或安全软件做 SSL 解密导致大文件传输失败（schannel 是 Windows 自带 SSL 库）。

解法

第1类（连不上），依次排查：

git config --global --get http.proxy
git config --global --get https.proxy
# 如有且无效：
git config --global --unset http.proxy
git config --global --unset https.proxy

若仍不行，临时关闭杀毒软件/安全卫士重试，或联系 IT 将 git.exe 加入防火墙白名单。

第2类（传输中断），依次尝试：

git config --global http.postBuffer 524288000
git config --global http.sslbackend openssl
git config --global http.version HTTP/1.1

设置后删除未克隆完整的安装目录，重新运行安装脚本。

兜底方案——手动复制：以上方法均无效时，install.ps1 的 Clone 失败提示新增"手动复制"选项。管理员将自己电脑上已克隆完整的知识库文件夹（必须包含隐藏的 .git 文件夹，先清理掉 .obsidian/workspace.json、.smart-env/ 等个人文件）通过内网共享盘/U盘拷给同事，同事复制到安装路径后，在脚本提示处输入 Y，即可跳过 clone 直接继续 Step 4-6（注册 vault、桌面快捷方式、自动同步）。后续日常同步是增量 git pull，数据量小，一般不会再触发同样的传输中断问题；但若该电脑对 github.com 完全无法连接，增量同步也会失败，需考虑换网络环境或使用 Gitee 镜像等方案。

安装 问题 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

同步 问题 15 同步时 .smart-env/event_logs/event_logs.ajson 冲突 ✅ 已解决

现象

Obsidian Git 弹出 conflict-files-obsidian-git，冲突列表里是 Not a file: .smart-env/event_logs/event_logs.ajson（不是内容冲突，而是"删除/修改"冲突，无 diff 可显示）。

原因

该文件早期被 Git 追踪，commit 05919e8 已将整个 .smart-env/ 移出追踪并加入 .gitignore（与 问题4 的 graph.json 同理）。Smart Connections 插件会持续写入这个本地缓存文件，所以那些早期克隆、本地仍保留旧追踪记录的同事，pull 到这个删除提交时，Git 发现"远端已删除、本地仍在改"，报"删除/修改"冲突。

解法

sync.ps1/sync.sh 已更新（2026-06-11）：冲突自动修复逻辑新增对 .smart-env/ 路径的处理——执行 git rm --cached -f 将其彻底移出 Git 追踪（本地缓存文件保留不受影响），再自动提交。同事再次运行同步（或等待自动同步触发）即可自动解决，无需手动操作。

遗留冲突卡住的同事，若想立即解决也可手动执行：

git rm --cached -f .smart-env/event_logs/event_logs.ajson
git commit -m "resolve conflict"
git pull

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

现象

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

原因

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

解法

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

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

2026-06-11 更新：若使用 Clash Verge 等本地代理软件，git 不会自动读取 Windows 系统代理，即使代理软件已开启也会报此错。sync.ps1 已加入自动检测逻辑（见"代理自动探测"），每次同步前优先读取 Windows 系统代理设置（注册表 Internet Settings），自动适配 Clash Verge / V2rayN / SSR 等任意已开启"系统代理"的软件，无需手动配置；若系统代理未开启，再退而检测本机 127.0.0.1:7897/7890 端口作为兜底。

2026-06-11 补充：早期同事在 install.ps1 安装阶段反复 Clone 失败，多半也是同一原因——浏览器能打开 GitHub（走了系统代理），但 git clone 不读系统代理直接连接失败。install.ps1 的 Step 3 已同步加入相同的代理自动检测逻辑，新装机的同事不会再遇到这个问题。

同步 问题 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，同事才能自动激活样式。

AI 助手插件（Claudian）

插件 问题 14 Claudian 报错 authentication_failed / ERR_BAD_REQUEST（连不上 Anthropic / OpenAI） ✅ 已解决

现象

Obsidian 中 Claudian 插件（realclaudian，嵌入 Claude Code / Codex 等智能体）对话时报错：

• Error: authentication_failed Not logged in · Please run /debug
• Unable to connect to Anthropic services / Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

原因

Claudian 底层调用本机安装的 claude / codex CLI 子进程：

1. CLI 本身需要先登录认证（Claude.ai 账号 / API Key，或 ChatGPT 账号）
2. 更常见的原因：api.anthropic.com、api.openai.com 在国内网络下需要走代理（VPN）才能访问。Clash Verge 等代理软件即使开启了"系统代理"，Node.js 子进程也不会自动读取 Windows 系统代理设置——只有显式设置 HTTPS_PROXY / HTTP_PROXY 环境变量才生效。Obsidian 作为独立桌面程序启动时不会带上终端里临时设置的环境变量。

解法

第一步：确认 CLI 已登录

在 PowerShell 中运行 claude（或 codex login status），按提示用 Claude.ai / ChatGPT 账号登录，或配置 API Key。

第二步：查找本机代理端口

打开 Clash Verge（或其他代理软件）的"概览"页面，记下"混合端口"（Mixed Port，常见默认值为 7897），确认系统代理已开启（不需要切换到全局模式，规则模式即可）。

第三步：在 Claudian 设置文件中为对应 provider 添加代理环境变量

编辑 .claudian/claudian-settings.json，在 providerConfigs.claude（以及如使用 Codex，providerConfigs.codex）的 environmentVariables 字段中填入：

HTTPS_PROXY=http://127.0.0.1:7897
HTTP_PROXY=http://127.0.0.1:7897

（多个变量用 \n 换行分隔，端口号替换为自己代理软件的实际端口）

第四步：完全重启 Obsidian

检查系统托盘确认 Obsidian 进程已退出（不是仅关闭窗口），重新打开后再测试 Claudian 对话。

注意：.claudian/ 目录是每人本地的插件状态/配置，不会通过 git 同步给同事。每位想用 Claudian 的同事都需要按上述步骤、用自己电脑上的代理端口单独配置一次。

---

.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/ 下的文件 → 自动采用远端版本并提交
   • .smart-env/ 下的文件 → 自动 git rm --cached -f 移出追踪并提交（本地缓存文件保留，见问题15）
   • 其他文件 → 报错提示联系管理员，不自动处理
3. 网络错误识别：识别 Could not connect / unable to access 等字样，输出”请检查网络/VPN”的明确提示
4. 路径兼容：自动探测 ASK知识库 和旧版 ASK 两种安装路径
5. 代理自动探测（Windows，2026-06-11 起）：每次 git pull 前先读取 Windows 系统代理设置（注册表 HKCU:\...\Internet Settings 的 ProxyEnable/ProxyServer），若已开启系统代理则自动设置 HTTPS_PROXY/HTTP_PROXY 环境变量后再执行 git pull——这种方式适配 Clash Verge、V2rayN、SSR 等任意已勾选”系统代理”的软件，不依赖固定端口；若系统代理未开启，再退而检测本机 127.0.0.1:7897 / 7890（Clash 系常见端口）作为兜底。未检测到任何代理则直接连接。每次同步独立检测，无需手动维护 git 全局代理配置，代理软件开关状态变化会自动适应。install.ps1 的 Step 3（Clone）已加入相同逻辑。

---

手动打包知识库副本（应急安装方案）

适用场景：同事电脑无法通过 git clone 下载知识库（参见”问题 13”），需要管理员把自己电脑上已有的副本打包分发，让同事手动复制后继续走 install.ps1 的 Step 4-6。

第一步：打包前准备

1. 确保自己电脑的知识库是最新状态：

   cd E:\OneDrive\ASK知识库
   git status   # 确认是 clean，没有未提交的修改
   git pull     # 拉取最新

2. 不要直接在 OneDrive 同步目录里压缩，先把整个文件夹复制一份到临时目录（如 D:\temp\ASK知识库），避免 OneDrive 占用文件导致压缩失败或体积异常。

第二步：打包内容清单

内容	是否打包	说明
所有内容文件夹（01_领域知识、02_项目档案、03_提案素材库、04_方法论与SOP、Templates、Members、Scripts 等）	✅ 是	知识库主体
.git/	✅ 必须包含	隐藏文件夹，是让副本变成可同步仓库的关键。文件资源管理器需先开启”显示隐藏的项目”才能看到
.gitignore、首页.md 等根目录文件	✅ 是
.obsidian/（除下方排除项外）	✅ 是	包含插件、CSS snippet、配置等共享设置

第三步：打包前需删除的个人文件

这些文件/文件夹已在 .gitignore 中，属于你本人电脑专属，不应该带给同事（带过去也不会生效，只会造成体积浪费或显示混乱）：

cd D:\temp\ASK知识库
Remove-Item .obsidian\workspace.json -ErrorAction SilentlyContinue
Remove-Item .obsidian\workspace-mobile.json -ErrorAction SilentlyContinue
Remove-Item .obsidian\graph.json -ErrorAction SilentlyContinue
Remove-Item .obsidian\cache -Recurse -ErrorAction SilentlyContinue
Remove-Item Personal -Recurse -ErrorAction SilentlyContinue

.smart-env/（本地向量索引）保留——已纳入同步，带给同事可以省去他们本地重建索引的等待时间（详见”问题 7”）。

第四步：压缩与分发

1. 压缩整个 D:\temp\ASK知识库 文件夹为 zip（建议用 7-Zip 或 Windows 自带”压缩为ZIP”，确保 .git 这种隐藏文件夹也被打包进去——某些压缩工具默认跳过隐藏文件，打包后务必解压验证一下 .git 是否还在）
2. 通过公司内网共享盘、企业网盘或 U 盘传给同事（不建议用邮件，体积通常较大）
3. 告知同事目标解压路径：D:\ASK知识库（或其 Documents 下的 ASK知识库，与 install.ps1 的自动选盘逻辑一致——D盘可用空间 > 5GB 用 D 盘，否则用 Documents）

第五步：同事侧操作

1. 解压收到的压缩包到目标路径，确保文件夹名是 ASK知识库，且根目录下能看到（开启”显示隐藏的项目”后）.git 文件夹
2. 双击运行 点击这里安装知识库.bat（或 install.ps1）
3. Step 0-2 正常走完后，Step 3 会检测到 $InstallPath\.git 已存在，直接跳过 clone（提示”Repo already exists”），继续走 Step 4-6
4. 后续按提示设置 Git 提交身份（姓名/邮箱），完成 vault 注册、桌面快捷方式、自动同步定时任务

验证清单

• 同事电脑上 D:\ASK知识库\.git 存在
• 在 D:\ASK知识库 下运行 git status 能正常输出（不报 “not a git repository”）
• 运行 git remote -v 能看到指向 ASK-jialingxiao/ASK-knowledge-base.git 的远程地址
• Obsidian 能正常打开 vault，首页统计数字正常显示

---

常用管理员操作

推送更新给所有同事

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

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