让笔记直达
你自己的 NAS。

先分清现在与未来

“直连”是客户端直接访问你的 NAS。“Touyu Direct”是计划中的自动化产品。两者不是同一个上线状态。

当前客户端支持也有限：iOS 和 Web 已有自定义服务地址路径；Android 尚未把设置值接入网络客户端， Windows 与 macOS 仍受 Tauri 网络 capability 限制。现在不能把手动直连当作五端都已完成的能力。

准备网络和域名

当前手动路径面向能管理家庭网络和 TLS 的用户。本页不提供 Private Server 安装包；请从你已经在运行的实例开始。

• 一台持续在线的 NAS 或主机，Private Server 只在内网端口 7080 提供 HTTP。
• 一个你控制的域名或子域名，例如 note.example.com。
• 至少一条可从公网入站的路径：公网 IPv4、全球可路由 IPv6，或两者都有。
• 路由器和 NAS 防火墙的管理权限，以及能终止 TLS 的 Caddy、Nginx Proxy Manager 或系统反向代理。
• 有效的公开 CA 证书；正式客户端不接受普通局域网 HTTP，也不应关闭证书或主机名校验。
• 如果使用 Web，Private Server 还必须允许实际 Web 页面 origin 的 CORS。

判断 IPv4、IPv6 与 CGNAT

未来的 Direct 不会要求你选择“IPv4 模式”或“IPv6 模式”。它会分别验证两条路径，只发布真正可达的记录。 今天手动设置时也应遵守同一原则。

判断是否处于 CGNAT 或双重 NAT 后面

1. 打开路由器状态页，记下 WAN IPv4。
2. 用浏览器访问可信的公网 IP 查询服务，比较它显示的 IPv4。
3. 如果 WAN 地址属于 100.64.0.0/10、10.0.0.0/8、 172.16.0.0/12 或 192.168.0.0/16，你位于 CGNAT 或上级路由器之后。
4. 如果两个地址不同，也要检查光猫或上级路由器是否还做了一层 NAT。

CGNAT 下普通端口转发不会生效。可以向运营商申请公网地址。计划中的 Touyu 客户端会在 Direct 超时、入站端口不可用或客户端与 NAS 的 IP family 不匹配时自动尝试 Relay。

IPv6 不是“有地址就能用”

只发布全球可路由的 IPv6。fe80::/10 link-local 和 fc00::/7 ULA 不能从公网到达。反向代理必须监听 IPv6 TCP 443，路由器与 NAS 防火墙也要明确放行。 错误的 AAAA 记录可能让证书签发和双栈客户端都优先走向一条坏路径。

今天手动完成直连

下面是当前自有域名路径。Touyu 不替你修改 DNS，不签发证书，也不会自动把 URL 送到客户端。

确认数据经过哪里

自有域名和未来 Touyu Direct 都是“发现与连接”方案，不会把 Private Server 变成 Touyu 云端的副本。

• Touyu Account 负责登录和 token 签发，不存笔记正文。
• 当前自有域名路径由你的 DNS 提供商保存 DNS 记录，Touyu 不管理 DNS 或证书。
• 未来 Direct Registry 只需要保存实例、随机 hostname、已验证公网地址和状态，不转发笔记流量。
• 证书私钥只留在 NAS 的反向代理 volume 中，不应上传给 Touyu 或 DNS 提供商。
• 未来 Relay 只改变传输路径。它转发到同一个 Private Server，不把数据改写到 Public Note Server。

理解设置状态

今天可以把这些状态当作手动检查点。未来 Direct 上线后，安装页应按同样顺序自动推进，而不是在失败时继续发布 DNS。

运行精确检查

把示例域名替换为你的真实 HTTPS hostname。两个端点都允许匿名访问；检查时不需要也不应该粘贴 bearer token。

检查 HTTP 状态与 JSON

BASE_URL="https://note.example.com"
curl --fail --silent --show-error "$BASE_URL/api/health"
curl --fail --silent --show-error "$BASE_URL/api/capabilities"

$BaseUrl = "https://note.example.com"
curl.exe --fail --silent --show-error "$BaseUrl/api/health"
curl.exe --fail --silent --show-error "$BaseUrl/api/capabilities"

两次请求都必须返回 HTTP 200。/api/health 的 JSON 形状是：

{"status":"healthy","version":"..."}

status 必须精确等于 healthy。version 是当前服务器版本，会随发布变化。

/api/capabilities 必须返回 contract major version 1，并包含当前功能列表：

{
  "apiVersion": "1",
  "version": "...",
  "features": [
    "notebooks", "notes", "tags", "sync", "vault",
    "attachments", "trash", "versions", "launch-handshake"
  ]
}

检查 DNS 与 TCP 443

Resolve-DnsName note.example.com
Test-NetConnection note.example.com -Port 443

DNS 结果只能包含已验证可达的 A/AAAA。TcpTestSucceeded 必须为 True。 再从外部网络打开 https://note.example.com/api/health，确认浏览器没有证书警告。

确认内部端口没有暴露

从家庭网络之外访问公网地址的 TCP 7080 必须失败。只有反向代理能在内网访问 Private Server 的 7080。

按症状排查

从最外层开始检查：DNS → TCP 443 → TLS → 反向代理 → API。不要跳过前一层去改后一层。

守住安全边界

把 Private Server 放到公网不等于把 NAS 管理面放到公网。只开放完成 HTTPS 直连所需的最小入口。

• 公网只开放 TCP 443；不要直接开放 7080、数据库、文件共享或 NAS 管理端口。
• 不要关闭 TLS 证书、主机名或重定向 origin 校验来“让检查通过”。
• 不要在 URL 中放用户名、密码、token 或其他 userinfo。
• DNS API 凭据只能拥有所需 zone 的最小权限。未来官方 Direct 也不会要求 NAS 持有 Touyu 主域凭据。
• 保持 NAS、反向代理和 Private Server 更新，并为本地数据与证书 volume 做独立备份。
• 注销实例或停用域名时，删除 DNS 记录、撤销设备 token，并停止旧 hostname 的监听。
• 只信任 note.touyuapp.com 发布的状态说明；当前没有官方 Direct 下载或一键绑定入口。