安装和信任证书

1. 证书安装（macOS）

平台说明：证书安装仅限 macOS，Windows 和 Linux 无需此步骤。

1.1 为什么需要证书

ALiang Gate 通过本地生成的 CA 证书来识别和路由 AI 流量（如 OpenAI、Claude、Cursor、VS Code 等）。当你的应用发起 HTTPS 请求时，ALiang Gate 利用该证书进行 TLS 代理，从而实现智能路由和加速。

简单来说：没有安装并信任证书 → AI 流量无法被识别 → 无法加速。

🔒 安全说明：证书仅用于识别和加速 AI 流量，不会记录或传输你的任何数据。证书存储在你的设备本地（~/.aliang/ 目录下），不会被第三方获取。

技术细节

• 证书类型：MITM CA（中间人证书颁发机构）
• 证书通用名称（CN）：aliang
• 颁发机构：aliang.com
• 密钥长度：RSA 2048 位
• 有效期：10 年
• 存储位置：macOS 系统钥匙串（/Library/Keychains/System.keychain）

1.2 安装证书

1. 打开管理面板 http://localhost:56431
2. 在仪表盘左侧的 「网络状态」 区域，找到证书状态卡片
3. 点击 「重新安装」 按钮
4. 系统会弹出 macOS 授权提示，输入密码或使用 Touch ID 确认

💡 提示：首次使用时，证书会在你点击安装按钮时自动生成，无需手动操作。

安装过程中发生了什么？

当你点击安装后，ALiang Gate 会执行以下操作：

1. 检查证书：在 ~/.aliang/ 目录下查找是否存在已有的 CA 证书（mitm-ca.pem）
2. 生成证书（如果不存在）：使用 RSA 2048 位密钥生成自签名 CA 证书
3. 调用系统命令：执行 macOS 的 open 命令打开证书文件
4. 系统导入：macOS 自动弹出「钥匙串访问」应用，显示证书添加对话框

安装完成后，系统会自动打开 钥匙串访问（Keychain Access），证书被导入到 「系统」 钥匙串中。

此时打开证书管理弹窗（点击 「详情」），可以看到证书状态为 「已安装」，但尚未信任。比如：

⚠️ 注意：如果系统弹出「是否要将此证书添加到钥匙串？」的对话框，请选择 「系统」 钥匙串并点击「添加」。如果只看到证书信息窗口而没有弹出添加对话框，说明证书可能已经存在，请继续下一步手动信任。

1.3 信任证书（钥匙串操作）

证书安装到系统后，还需要在 macOS 钥匙串中手动将其设为信任。这是最关键的一步，没有信任的证书无法正常工作。

操作步骤

第一步：打开钥匙串访问

• 如果安装步骤中已自动打开，直接使用即可
• 如果没有打开，可以通过以下方式手动打开：
  • 按 ⌘ + 空格 打开 Spotlight 搜索，输入「钥匙串访问」或「Keychain Access」
  • 或在「访达」中前往「应用程序 → 实用工具 → 钥匙串访问」

第二步：定位到系统钥匙串

1. 在钥匙串访问窗口的 左侧边栏 中，找到 「系统」 钥匙串（在「钥匙串」分组下）

2. 点击选中「系统」

   如果左侧没有显示边栏，请点击菜单栏的 「显示」→「显示钥匙串」 来打开边栏

第三步：找到 ALiang CA 证书

1. 在右侧证书列表中，找到名称为 aliang 的证书

2. 你可以通过搜索框输入 aliang 来快速定位

   💡 提示：如果找不到，检查是否选中了正确的钥匙串（「系统」）。如果仍然找不到，请回到管理面板重新安装证书。

第四步：打开证书详情

1. 双击 aliang 证书，打开证书详情窗口
2. 你会看到证书的基本信息，包括：
   • 通用名称：aliang
   • 颁发者：aliang.com
   • 有效期：自生成日期起 10 年

第五步：设置信任

1. 在证书详情窗口中，找到并点击 「信任」 左侧的 ▶ 展开箭头，展开信任设置区域

2. 你会看到多个信任选项，找到 「使用此证书时」（When using this certificate）

3. 当前值为「使用系统默认值」，点击右侧下拉菜单

4. 选择 「始终信任」（Always Trust），就像图片：

   ⚠️ 重要：必须选择「始终信任」，不能选择「使用系统默认值」。系统默认值不会信任自签名证书。

第六步：确认更改

1. 关闭证书详情窗口

2. 系统会弹出密码确认对话框，输入你的 macOS 登录密码（或使用 Touch ID）

3. 点击 「更新设置」

   如果你使用的是 Mac 笔记本，可能还会弹出 Touch ID 提示，可以直接用指纹确认。

完成！证书现在已经设置为「始终信任」。

整个过程快速参考图

打开钥匙串访问 → 选择「系统」钥匙串 → 找到「aliang」证书
→ 双击打开 → 展开「信任」→ 改为「始终信任」→ 输入密码确认

1.4 确认证书已信任

回到 ALiang Gate 管理面板（http://localhost:56431），刷新页面或点击证书管理中的状态刷新按钮。

确认证书状态变为 「已信任」 ✅。

证书状态必须为 「已信任」 才能正常加速 AI 流量。如果仍然显示其他状态，请参考常见问题。

ALiang Gate 如何检测证书信任状态？

ALiang Gate 使用 macOS 的 security 命令行工具来检测证书的信任状态。具体会检查以下三个层级的信任设置：

只要证书在任一层级中被标记为信任，状态就会显示为「已信任」。

1.5 证书状态说明

证书文件位置

1.6 常见问题

证书安装后状态仍显示「未信任」？

这是最常见的情况。安装证书只是将其导入到钥匙串中，信任需要手动设置。

请按照 1.3 节 的步骤在钥匙串中手动将证书设为「始终信任」。

如果你确认已经在钥匙串中设置了「始终信任」但状态仍然显示「未信任」，请尝试：

1. 完全退出并重新打开 ALiang Gate
2. 刷新管理面板页面
3. 如果仍然不行，尝试重启 Mac

安装时没有弹出钥匙串访问？

在某些情况下，open 命令可能会直接打开证书信息窗口而不是添加对话框。你可以：

1. 手动打开「钥匙串访问」应用
2. 将 ~/.aliang/mitm-ca.pem 文件直接拖拽到「系统」钥匙串中
3. 然后按照 1.3 节 设置信任

找不到 ~/.aliang/ 目录？

.aliang 是隐藏目录。在「访达」中：

1. 按 ⌘ + Shift + .（句号）来显示隐藏文件
2. 或在「访达」菜单中选择「前往 → 前往文件夹…」，输入 ~/.aliang/

需要重新安装证书？

在仪表盘的网络状态区域点击 「重新安装」，系统会执行完整流程：

1. 从钥匙串中移除旧的 CA 证书
2. 重新生成新的 CA 证书
3. 安装新的证书到系统

⚠️ 注意：重新安装后需要再次执行 1.3 节 的信任步骤。

需要导出证书？

点击 「详情」 打开证书管理弹窗，点击 「下载 PEM」 导出 PEM 格式证书文件。

导出的证书文件可以用于：

• 在其他 macOS 设备上安装
• 在 Linux 系统上配置信任
• 备份证书

证书安装失败，提示权限错误？

ALiang Gate 安装证书时需要管理员权限。请确保：

1. 你的 macOS 账户具有管理员权限
2. 当系统弹出授权提示时，正确输入了密码或使用了 Touch ID
3. 如果使用「系统偏好设置 → 安全性与隐私」限制了应用安装，请在设置中允许 ALiang Gate

多个 ALiang 证书残留？

如果你多次安装或卸载过 ALiang Gate，钥匙串中可能存在多个旧证书。可以手动清理：

1. 打开钥匙串访问
2. 在「系统」钥匙串中搜索 aliang
3. 删除所有旧的 aliang 证书
4. 回到管理面板重新安装

1.7 Windows 用户说明

Windows 用户无需手动安装和信任证书。ALiang Gate 在 Windows 上会通过 PowerShell 自动将证书安装到系统的「受信任根证书颁发机构」存储区，安装完成后即为信任状态。

Windows 证书存储位置：

• 当前用户：Cert:\CurrentUser\Root
• 本地计算机：Cert:\LocalMachine\Root

最后更新：2026-05-29