Oxynote

为什么选择 Oxynote？

Grafana 提供的面板说明位置是描述字段，也就是藏在信息图标后面的工具提示；Grafana 自己的文档还建议说明要简短。要是把说明放在 Notion 里，图表就只能以嵌入式 Grafana 面板的形式出现在那里，而且只有已经登录 Grafana 的人才能看到；在 Grafana Cloud 上则完全无法显示。每种工具都有自己的历史记录，因此没人会把图表及其说明作为同一项更改来审核。在 Oxynote 中，图表会在页面内运行自己的查询，说明就是你在图表下方输入的内容，而草稿分支会将二者一起带入一次差异对比和一次审批。

长篇版本有点像在发牢骚，但它解释了个人层面的原因

很长一段时间里，我公司最可靠的文档，就是我和自己在 Slack 上的聊天记录。这种情况是怎么形成的，要从仪表盘说起。我们有很多仪表盘：Grafana、Sentry，不知为何还有一点 Datadog，以及一些带图表的自托管 HTML 页面。此外，我还被鼓励为自己负责的部署运行健康检查（为什么不能放在 Grafana 或类似工具里，没人能告诉我）。这些部署是通过 websockets 拉取金融市场数据的服务。在高负载下，它们会发生内存泄漏，最终因 OOM 被杀死。里面有个 bug，我们一直在追查，却有一阵子始终找不到；与此同时，每次进程被杀都会导致事件遗漏，而事件遗漏意味着要手动运行回填脚本。我们的仪表盘都没有显示这些情况。于是我就用了 cron，用 curl 请求每个服务的状态端点，再把结果私下发到 Slack 给自己。这一点也不方便。

此外还有其他各种事情。内部 wiki 仍在描述已经结束的试用产品的部署流程。密钥库。服务器管理命令和 curl 请求。它们散落各处，访问权限本身也是个问题：每一项都有不同的负责人可以授予权限，所以我花了很多时间先弄清楚负责人是谁，再找到他们。由于我们在 Slack 上沟通，我就在那里索要所有这些信息，人们也在那里回复，有时甚至直接发明文凭据（太可怕了）。为了不丢失任何信息，我把那些消息转发到和自己的聊天中，结果这段聊天记录长期以来成了我的事实来源：从我们众多的 Grafana 仪表盘中挑出的、真正重要的特定仪表盘链接；请求和响应都没有任何文档记录的其他团队服务的 curl 请求示例，方便我集成时对照它们的响应；还有服务器 IP 地址，以及各处部署了什么的备注。 当然，我确实试着解决过这个问题。我写了 Notion 文档，并在文档中链接 Grafana 图表，这样做了一段时间还不错。后来它们逐渐脱节。一篇文档解释了我们摄取速率图表上的标签，比如 market、region 等，但新标签不断增加，却没人记录，其中一半甚至没有用在图表上，而且每个标签都会让 Prometheus 多生成一个时间序列。要让文档和图表保持同步，就得在两边都添加链接，既要在 Notion 中添加，也要在 Grafana 中添加，这比我愿意做的工作多得多；还得切换浏览器标签页，只为确认说明和图表表达的内容仍然一致。而这还只是可观测性。除此之外，管理操作需要发送特定的 curl 请求，功能标志则放在一个与其他一切都脱节的服务里。所有这些都值得有一套完善的审核流程，就像在 GitHub 上那样，并能对文本、指标图表及其他可视化结构进行差异比较。但实际上，这样的流程完全不存在。

David（@davseby）和我（@swithek）一起创办了 Oxynote。第一次值班时，他在另一家公司需要摸清一个系统及其文档。他多年使用 Grafana 和内部文档，本以为这会是例行工作。但他遇到的却是自己从未用过的 Datadog，以及结构迥异的 Notion。接着，就在他第一次值班期间，负责丰富图像元数据的服务发生故障。对用户上传内容的搜索结果变得不准确，问题随后在整个产品中连锁蔓延。监控告警触发了，但没有任何告警链接到相关位置，也没有说明是哪个服务开始出问题，让他只能手动梳理各种关联，度过了一个令人神经紧绷的夜晚。显示某个服务过载且无响应的指标一直都在那里。不过 Datadog 的 UI 错综复杂，也没有任何说明解释各个图表追踪的内容，所以 David 始终没能找到它。连接到 Datadog MCP 服务的 AI Agent 找到了。

我们俩想要的都是把图表、说明、命令和功能标志放在同一页面上，一起编辑，像代码一样审核，并且无论是深夜疲惫的人还是 Agent 都能读懂。我们用过的每种工具都只擅长其中一件事，而且从不关注其他方面。这正是 Oxynote 要填补的空白。它从我们最需要的部分入手：类似 Notion 的实时文档、指标图表、审核流程，以及类似 Stripe 的实时系统拆分文档。拼图的其他部分也即将推出。

快速开始

Oxynote 是一个容器。只需执行以下操作：

docker run -d --name oxynote \
  -p 8080:8080 \
  -v oxynote_data:/oxynote/data \
  ghcr.io/oxynote/oxynote:latest

打开 http://localhost:8080，并使用 [email protected] 和 oxynote-admin-1234 登录。

如需从源代码运行，请参阅 CONTRIBUTING.md。

包含内容

指标网格

Live Metrics 块展示时间序列、柱状图或仪表盘，由一个或多个 Prometheus 或 SQL 查询构建；SQL 端支持 PostgreSQL、MySQL 和 MariaDB。指标网格由多个这样的块并排组成。在 Grafana 中，这会是一个仪表板。在 Oxynote 中，它是页面内的仪表板，因此说明可以围绕图表展开：图表展示什么、阈值为何设在那个位置、超出阈值时该怎么做，都能与图表放在同一页面上。

评审

任何页面都可以设为可评审，此后所有更改都会进入草稿。差异视图能理解内容块，而不只是文本：重命名的端点、重命名的响应字段和改写的句子都会在同一视图中就地以红色和绿色显示。评审者批准后，草稿就会合并到 main；还可以保护 main，防止任何人直接编辑。

协作

页面实时编辑，因此你可以看到谁在页面上、各自选中了哪个内容块以及正在何处输入，而且不会有人覆盖他人的内容。评论可以附加到某个词、图表源码中的某一行或整个图表上，可以添加回复，并会在更改提交后标记为已解决。每条提及和回复都会进入你的收件箱。

其他功能

• 内容块：标题、列表、待办清单、引述、带标题的代码块、提示框、图片、文件、Figma 嵌入内容、Mermaid 图表。
• 内容新鲜度钩子：内容块或页面会追踪其依赖的 GitHub 文件、容器镜像、网页或日期；这些内容发生变化时，会提醒其维护者。
• 页面树（含子页面）、标签、全文搜索、适用于所有操作的键盘快捷键，以及浅色和深色主题。
• 工作区支持邀请、GitHub 和 Slack 应用，以及通过 GitHub、Google 或 Slack 社交登录。
• 内置助手 Rubber Duck 可以编辑页面，并运行与内容块相同的查询；你可以选择使用 Anthropic、OpenAI、Google、OpenRouter 提供的大模型，或通过 Ollama 使用本地模型。Claude Code 和 Codex 等 MCP 客户端也可以通过 OAuth 使用相同的工具。

刻意保持简单

简单说说它适合哪些人。

如果你：

• 向其他技术人员讲解系统，并希望将指标图表和说明放在同一页面上
• 想为内部服务创建 Stripe 风格的文档，但不想使用文档生成器
• 希望页面更改像拉取请求一样，经过草稿、差异对比和审批
• 希望团队成员和 Agent 都能阅读同一个页面
• 希望自托管

那么 Oxynote 适合你。

如果你：

• 想要托管服务。目前还没有
• 想要适用于整个公司的 Wiki。Oxynote 面向技术人员及其运行的系统
• 想要包罗万象的所有选项。Oxynote 有自己的主张，提供良好的默认设置，并尽量减少选项

那么 Oxynote 可能不适合你。

常见问题

它能取代 Grafana 吗？ 这是我们的目标。目前它支持来自 Prometheus 和 SQL 的指标图表及仪表盘式网格，并可在旁边撰写说明。日志和告警功能尚未提供，但我们正在开发。

为什么取这个名字？ 我们最初在内部将它称为“会呼吸的文档”。呼吸需要氧气，所以我们以 oxy 为前缀，再加上 note。

社区

加入 Discord，提出问题、分享 Oxynote 的使用方式，并与开发者交流。发现了 Bug 或有新想法？提交问题。