从安装到日常，一页讲清楚。

下载与安装

知屿是 Windows 桌面应用，资料默认保存在本机，无需注册账号。

1. 安装包目前没有代码签名，Windows 可能弹出提示。请只从 GitHub Releases 下载，并对照 SHA256 校验文件。
2. 升级时直接覆盖安装，资产、文档与密钥库都会保留；升级前建议先做一次加密备份（见备份）。
3. 不需要安装 Node.js 或其他运行环境。macOS 目前只提供未签名的测试包，见 macOS 说明。

首次使用

1. 工作区名称：显示在左下角，可以随时在「个人资料」里修改。
2. 主密码：10 至 256 位，用来加密密钥库里的密码、API Key 和 SSH 凭据。主密码无法找回，请妥善保管。
3. Linux.do 登录（可选）：只用于绑定主身份和同步昵称、头像，不上传本机资产，也不能代替主密码。
4. 进入后，首页的「快速开始」列出五步：添加第一项资产、记录费用与续费日、写一篇运维文档、关联两项资产、用标签分组。每完成一步会自动打勾；不需要时点「不再显示」。

不确定从哪里开始？按 Ctrl K 搜「模板」，从一个常用订阅开始，续费日历和每月支出马上就有内容。

界面导览

左侧导航按用途分成四组：工作台（资产总览、费用与续费、文档、AI 助手）、基础设施（服务器、节点、域名、证书、服务资产）、账号与订阅（AI 订阅、用量记录、邮箱、号码）和安全与整理（密钥库、标签）。

• Ctrl K 打开搜索：资产、页面、标签和常用操作（切换主题、订阅模板、续费日历）都能直接搜到。
• 点任意资产，详情在页面里打开，面包屑显示所在位置；Esc、Alt ← 或左上角「返回」回到原列表，筛选和滚动位置都还在。
• 窗口较窄时点左上角按钮收起侧栏，只保留图标；按 ? 查看全部快捷键。

添加资产与订阅模板

点侧栏「新建资产」或按 Ctrl N，选择要记录的类型：

订阅模板：在同一个窗口下方的「从常用订阅开始」，选 ChatGPT Plus、Claude Pro、Cloudflare Workers、iCloud+、Netflix 等，名称、金额、周期和下次续费日都已经填好，保存前可以修改。也可以在 Ctrl K 里搜「模板」。

自定义资产类型

1. 点「新建资产」，在窗口里的「自定义资产」分区点「新建自定义类型」（或 Ctrl K 搜「自定义」），填写名称、选一个图标。
2. 添加字段（最多 12 个）：文本、链接、日期或数字，比如「内网地址」「管理页面」「购入日期」。
3. 保存后直接进入添加表单，填写字段，还可以照常填费用、到期日和标签；之后在同一分区点类型卡片就能添加这一类资产。
4. 「服务资产」页上方的类型按钮可以只看某一类，「管理类型」里修改或删除类型；删除类型不会删除资产，它们回到「其他服务」。

字段内容明文保存在本机，不要填写密码或密钥；凭据请放进密钥库，再通过关联连接到资产。

资产详情与关联

详情页左列是资产本身和监控指标，右列是关联资产、关联文档和凭据位置。服务器还有自建节点、服务文档、绑定密钥、运维工具和 SFTP 分页。

1. 在右列「关联资产」里选择另一项资产并添加，比如把网站、证书、数据库只读账号都关联到它所在的主机。
2. 点「搜索与多选关联」可以一次关联多项。
3. 之后在左侧「标签 → 关系图」或任意列表切到关系图视图，能看到所有已确认的连接：某台主机出问题时，牵连哪些网站、订阅和恢复手册一目了然。
4. 「发现关联」会根据相同主机地址、共同标签或文档标题给出建议，勾选确认后才写入。

费用与续费日历

1. 编辑服务器、域名、服务资产或号码时，填写金额、币种（CNY / USD）、周期（每月 / 每年 / 一次性）和到期日。AI 订阅填写美元月费与续费日。
2. 「费用与续费」页顶部按月、按年折算支出；人民币和美元分开合计，填写汇率后可统一折成人民币。
3. 续费日历按资产类型配色，月付、年付的资产会按周期推算之后的续费日（空心标记）。点任一天，右侧列出当天要处理的事项。
4. 首页「近期续费」列出未来 14 天的续费；「到期时间线」可导出 ICS，导入手机或电脑日历提醒。
5. 续费完成后点「已续费」，到期日按月付或年付顺延一期，提示里可以撤销；「让 AI 规划」会让 AI 按紧急程度排出续费顺序和合计金额。

备忘提醒与推送

1. 在「费用与续费」的「备忘提醒」点「新建提醒」：写下事项、日期，选择是否每周 / 每月 / 每年重复，以及提前几天提醒。
2. 卡片上的大号数字是倒计时；处理完点 ✓，重复的自动顺延到下一期，提示里可以撤销。首页「近期续费」也会列出 14 天内的提醒。
3. 桌面版到时间会弹系统通知；在「设置 → 邮件推送」勾选「续费与备忘提醒也推送到这个渠道」，提醒会发到 Telegram、微信（Server酱 / WxPusher）或企业微信。
4. 资产到期前多少天开始提醒，在「设置 → 后台运行」调整。

网页版（自托管）

1. 在服务器上下载仓库里的 docker-compose.yml，运行 docker compose up -d（镜像 ghcr.io/songwo/zhiyu-web，支持 amd64 / arm64），用 docker compose logs zhiyu 找到「设置口令」。
2. 浏览器打开 http://服务器:8848，用设置口令创建登录账号；之后在家和公司都用这个账号登录同一份资料。
3. 密钥库在浏览器里用主密码解密，服务器只保存密文。放到公网前请用 docker-compose.https.yml 加域名（自动 HTTPS，知屿不直接暴露端口）。
4. 安全设置：登录后在「设置 → 个人资料 → 账号安全」开启两步验证（TOTP）并保存 8 个恢复码；在服务器上用 ZHIYU_ALLOWED_NETS 只允许自己的 IP 或 VPN；登录失败会被限流，新地址登录会推送到手机，登录中的设备可以随时退出。
5. 「设置 → 提醒推送」可以让服务器按时把续费与备忘提醒推送到 Telegram、微信或企业微信，浏览器关着也能收到。
6. 「设置 → 数据」可以下载加密备份到桌面版恢复，也能把桌面版备份恢复到网页版。
7. 网页版改由服务器执行 SSH 终端、SFTP、主机采集、域名与证书检查、Cloudflare、AI 助手和用量刷新；另有「主机监控」页，显示这台 VPS 自己的 CPU、内存、磁盘、网络。浏览器插件配对、浏览器密码 CSV 迁移、OAuth 网页登录、v2rayN 流量等仍只在桌面版。

完整步骤、环境变量、HTTPS 示例和「安全加固」清单见仓库里的 docs/WEB.md。

桌面与网页版同步

让桌面版和你自己服务器上的网页版保持一致，两边都能改，合并后一致。需要两边都升级到 1.17.0 或更新。

1. 登录网页版，打开「设置 → 同步」，点「生成配对码」。配对码 5 分钟有效，只能用一次。
2. 在桌面版打开「设置 → 同步」，填入网页版地址（例如 https://zhiyu.example.com）和配对码，点「配对」。
3. 配对成功后，两边会显示同一个「服务器指纹」，可以核对确认连的是这台服务器。之后每 2 分钟和每次修改后自动同步，也可以点「立即同步」。
4. 在「同步哪些内容」里选择资产与关联、文档；密钥库默认不同步，开启后只传密文，且两边必须使用同一个主密码。

系统加密保存的 Cloudflare Token、模型 API Key、图床 Key 等不参与同步，需要在网页版重新填写。想看协议是怎么保护你的，打开协议动画；设计、威胁模型和已知限制见 docs/SYNC.md（自研协议组合，未经第三方审计）。

端口与容器监控

1. 先为服务器配置 SSH（见「添加资产」）。打开服务器详情，切到「端口与容器」，点右上角刷新。之后随「设置 → 监控采集」的周期自动更新。
2. 知屿通过 SSH 只读执行 ss（或 netstat）与 docker ps / inspect / stats，不会改动主机。显示监听端口（对外 / 内网 / 仅本机）、容器状态、健康检查、重启次数、CPU 与内存。
3. 没装 Docker、登录用户不在 docker 组、Docker 服务没运行时，会说明原因；原有的 CPU、内存、磁盘采集不受影响。
4. 容器反复重启、异常退出、因内存不足被终止、健康检查失败时，主机进入「注意」，并发系统通知；在「设置 → 邮件推送」勾选「续费与备忘提醒也推送到这个渠道」后也会推送到手机。同一问题 24 小时内只提醒一次。
5. 要让服务资产的状态自动更新：编辑服务，在「运行位置」里选择运行在哪台主机，填监听端口、选择 Docker 容器和对外域名。端口没在监听或容器停了会显示「告警」，关系图里自动连上主机与域名。

「对外」只表示监听在所有地址上，公网是否真的可达还取决于防火墙。登录用户看不到其他用户的进程名。网页版同样可用，由服务器通过 SSH 采集。

用量记录

用量页把四类数据分开统计，每类一种颜色：

• 本机 Token（紫）：读取 Codex、Claude Code、Grok Build、Gemini CLI 在本机保存的用量日志，默认开启，可在「采集与监控」中关闭。
• API Token（绿）：连接 OpenAI / Anthropic 组织 API，需要相应的查询权限。
• 流量增量（橙）：机场订阅链接或 3x-ui 面板，只累计两次采集之间的有效增量。
• 订阅额度（玫红）：在「AI 订阅」中授权的订阅账号，记录各窗口的已用百分比。

点「连接用量来源」添加机场、3x-ui 或 API；「订阅与来源」分页里每个来源一张卡片，显示连接状态、最近数值和失败原因。API 与订阅每 5 分钟自动更新，也可以点「刷新全部」。

文档

• 从「＋」新建，或把 Markdown 文件拖进窗口任意位置批量导入。
• 阅读时显示字数和阅读时长，底部「目录」一键跳到章节；点「编辑文档」才展开工具栏。
• 「关联与设置」把文档绑定到服务器、域名或账号，在资产详情里就能看到对应的手册。
• 安装浏览器插件后，可以把网页正文确认后保存为文档。

密钥库与网站账号

• 密码、API Key、SSH 私钥都用主密码派生的密钥（scrypt）以 AES-256-GCM 加密保存，锁定后需要重新输入主密码。
• 「浏览器密码」可导入 Chrome / Edge 导出的 CSV：先预览新增、重复和冲突，冲突时保留原记录。
• 网站账号支持 TOTP 动态验证码；浏览器插件在登录页给出同站账号建议，选中后填写。
• AI 助手只知道「凭据在哪里」，不会读取密钥库里的密码。

备份、恢复与换电脑

1. 「设置 → 数据 → 创建加密备份」：把资产、文档、密钥库、设置、对话、知识库和用量记录打包成一个 .zhiyu-backup 文件，用备份密码加密。
2. 换电脑时勾选「同时包含系统保护的凭据」，模型 API Key、云服务连接等也会一起迁移。
3. 「从备份恢复」先预览内容再确认；当前资料会保存为快照，可随时找回。
4. 「自动备份」按每天、每 3 天或每周写入你选择的文件夹，只清理自己生成的旧备份。

备份密码和创建备份时的主密码都无法找回，请一起记好。

AI 助手

• 在「设置 → 模型与知识库」选择 OpenAI 兼容服务、填写 API Key 和模型名，保存后测试连接。
• 可以问「哪些资产需要优先处理」「工作邮箱里有哪些账号」，回答会标出来源资产和文档。
• 勾选「本次生成修改建议」后，AI 会给出修改前后的对比，由你逐项确认才写入；查询实时邮件数量等需要单次授权。
• AI 发现缺少费用、到期日或运维文档时，会直接生成补全资产或新建文档（可关联资产）的建议；应用后点「打开文档」「查看资产」核对。
• 每个回答下方的「下一步」可以继续追问，或直接打开续费日历、页面和资产；资产详情的「问 AI」、首页待处理的「让 AI 逐项分析」会带好问题进入助手。

设置与个性化

• 头像菜单里的「系统设置」以页面打开；右上角的设置按钮和 Ctrl , 打开同样内容的弹窗。
• 「外观」可切换浅色 / 深色 / 跟随系统、语言，以及 100%–150% 界面大小。
• 「监控采集」设置主机指标的采样周期；本机连不上的主机，可以关掉它卡片右下角的「采集」开关，不再连接也不再告警；「邮件推送」可把新邮件数量推送到 Telegram、Server酱、企业微信或 WxPusher。
• 「存储」查看缓存占用并清理；「关于知屿」检查更新。

适合怎样使用

常见问题与排查