钥匙串

版本说明

钥匙串（Keychain）功能从 Obsidian v1.11.5 开始支持，用于安全存储敏感凭据信息。

概述

钥匙串是 Obsidian 内置的安全凭据管理功能，用于安全存储 API 密钥、密码等敏感信息。插件可以通过钥匙串安全地访问所需的凭据，而无需用户每次手动输入或将密钥明文存储在配置文件中。

为什么需要钥匙串？

在使用 AI 插件、同步插件等功能时，通常需要配置 API 密钥或其他敏感凭据：

传统方式	问题
直接写在配置文件	明文存储，存在安全风险
每次手动输入	操作繁琐，效率低
存储在笔记中	不安全，容易被误分享

钥匙串提供了一种安全、便捷的解决方案：

• 加密存储：凭据经过系统级加密保护
• 按需授权：插件访问凭据需要用户确认
• 集中管理：统一管理所有敏感凭据
• 跨设备同步：支持通过 Obsidian Sync 加密同步

设置钥匙串

打开设置

1. 打开「设置」→「钥匙串」
2. 首次使用会显示钥匙串功能介绍

添加凭据

点击「添加新凭据」按钮：

配置项:
  凭据 ID: 唯一标识符（如：openai-api-key）
  显示名称: 友好名称（如：OpenAI API 密钥）
  凭据内容: 实际的密钥或密码

命名规范

建议使用统一的命名规范，如 服务名称-凭据类型：

• openai-api-key
• github-token
• database-password

管理凭据

在钥匙串设置中，你可以：

操作	说明
查看	查看已存储的凭据列表（不显示实际内容）
编辑	修改凭据的显示名称
更新	更新凭据内容
删除	移除不再需要的凭据
导出	导出凭据配置（不包含实际密钥）

使用场景

AI 插件配置

许多 AI 插件需要配置 API 密钥：

# 插件会请求访问钥匙串中的凭据
插件请求: "需要访问 OpenAI API 密钥"
用户确认: 允许 / 拒绝

支持的常见 AI 服务：

服务	凭据类型	用途
OpenAI	API Key	ChatGPT、GPT-4 等
Anthropic	API Key	Claude 系列
Google AI	API Key	Gemini 系列
Azure OpenAI	API Key + Endpoint	企业 AI 服务

同步服务配置

配置第三方同步服务时：

• S3 存储的访问密钥
• WebDAV 的登录凭据
• 云服务的 API Token

Git 集成

使用 Obsidian Git 插件时：

• GitHub Personal Access Token
• GitLab Access Token
• SSH 密钥密码

数据库连接

连接外部数据库或 API：

• 数据库连接字符串
• API 认证令牌
• OAuth 凭据

安全特性

加密存储

钥匙串使用系统级加密技术存储凭据：

平台	加密技术
Windows	DPAPI (Data Protection API)
macOS	Keychain Services
Linux	Secret Service API / libsecret
iOS	iOS Keychain
Android	Android Keystore

访问控制

安全机制:
  插件请求凭据:
    - 显示请求来源
    - 显示请求的凭据名称
    - 用户必须手动确认
  自动拒绝:
    - 未授权的插件
    - 未知来源的请求

同步安全

通过 Obsidian Sync 同步钥匙串时：

• 端到端加密传输
• 服务器无法解密内容
• 只有你的设备可以访问

重要提示

钥匙串数据仅在启用 Obsidian Sync 时才会同步到云端。使用第三方同步方案时，钥匙串数据不会被同步。

跨平台支持

桌面端

系统	要求	存储
Windows	Windows 7+	DPAPI
macOS	macOS 10.13+	Keychain
Linux	libsecret 支持	Secret Service

Linux 系统要求

Linux 系统需要安装 libsecret 库：

# Debian/Ubuntu
sudo apt install libsecret-1-0 libsecret-1-dev

# Fedora
sudo dnf install libsecret

# Arch Linux
sudo pacman -S libsecret

如果系统不支持加密，Obsidian 会提示并提供降级方案。

移动端

系统	存储
iOS	iOS Keychain（系统级安全存储）
Android	Android Keystore（硬件级加密）

最佳实践

命名规范

使用清晰、一致的命名规范：

推荐格式:
  服务名-凭据类型: openai-api-key
  项目名-服务: myproject-github-token
  功能描述: ai-assistant-key

定期轮换

安全建议:
  - 定期更换 API 密钥
  - 为不同用途使用不同密钥
  - 及时删除不再使用的凭据
  - 监控 API 使用情况

权限最小化

• 只存储必要的凭据
• 使用具有最小权限的 Token
• 定期审查已授权的插件

备份策略

备份建议:
  - 使用 Obsidian Sync 同步钥匙串
  - 安全保存重要密钥的备份
  - 记录密钥的创建时间和用途

插件开发

请求凭据

开发者可以在插件中请求访问钥匙串：

// 请求访问凭据
const credential = await app.keychain.requestCredential({
  id: 'openai-api-key',
  message: '需要访问 OpenAI API 密钥以使用 AI 功能'
});

if (credential) {
  // 使用凭据
  const apiKey = credential.value;
}

存储凭据

// 存储新凭据
await app.keychain.setCredential({
  id: 'my-service-token',
  name: 'My Service Token',
  value: 'token-value'
});

列出凭据

// 列出插件可访问的凭据
const credentials = await app.keychain.listCredentials();

常见问题

钥匙串数据存储在哪里？

存储位置

钥匙串数据存储在系统级安全存储中，不在仓库文件夹内：

平台	存储位置
Windows	%APPDATA%\obsidian\keychain\
macOS	~/Library/Keychains/
Linux	~/.local/share/keyrings/
iOS	iOS Keychain
Android	Android Keystore

Linux 提示加密不可用怎么办？

Linux 加密问题

某些 Linux 发行版可能缺少必要的加密库：

1. 安装 libsecret 库
2. 确保桌面环境支持 Secret Service
3. 如果仍不可用，考虑使用 Obsidian Sync 加密同步

Obsidian v1.12+ 已添加对这种情况的处理。

钥匙串数据会同步到其他设备吗？

同步说明

• Obsidian Sync：支持加密同步钥匙串数据
• 第三方同步：不会同步钥匙串（如 Git、iCloud 等）
• 建议：在新设备上需要重新配置凭据，或使用 Obsidian Sync

如何迁移钥匙串数据？

迁移方法

推荐方式：

1. 使用 Obsidian Sync 同步到新设备
2. 在新设备上确认同步完成
3. 验证凭据可用

手动方式：

1. 记录所有凭据信息
2. 在新设备上重新添加
3. 删除旧设备上的敏感数据

忘记某个密钥怎么办？

密钥找回

钥匙串出于安全考虑不显示已存储凭据的内容。如果忘记密钥：

1. 在服务商后台重新生成新密钥
2. 在钥匙串中更新凭据
3. 使旧密钥失效

与相关功能对比

功能	用途	安全级别
钥匙串	存储 API 密钥、密码	高（系统级加密）
环境变量	临时存储配置	中（进程级）
配置文件	存储插件设置	低（明文）
笔记属性	存储笔记元数据	低（明文）

下一步

• AI 辅助功能 - 使用钥匙串配置 AI 插件
• 同步方案 - 配置安全的同步方式
• 安全与隐私 - 了解更多安全最佳实践