TouyuNote 头鱼笔记
Private Server connection guide

Your notes,
straight to your NAS.

This guide starts with what you can configure today, then shows what Touyu Direct will automate when it ships. With either direct path, note bodies and attachments travel from your client to your Private Server.

Set up today’s path Preview future Direct
01

Separate today from the future

A direct connection means the client reaches your NAS. Touyu Direct is the planned automation around that connection. They do not have the same availability.

Available now · manual

Bring your own domain

You manage the domain, A/AAAA records, TLS certificate, router, and reverse proxy, then enter the HTTPS URL in a client that supports custom servers.

Future goal · not live

One-click Touyu Direct

The planned setup agent detects the network, Registry validates and publishes DNS, Caddy obtains a certificate, and clients discover NAS instances on the same account.

Do not mistake a product design for a live service.

This page offers no Direct download and does not claim that any direct.note.touyuapp.com hostname has been assigned. Stop if a third party asks you to download an “official Direct installer” or hand over credentials for your primary DNS account.

Client support is also incomplete today. iOS and Web have custom-server URL paths. Android does not yet apply its setting to the network client, and the Windows and macOS apps are still blocked by Tauri network capabilities. Manual direct access is not a finished five-client feature.

02

Prepare the network and domain

Today’s route is for operators comfortable with home networking and TLS. This page does not distribute a Private Server package; start with an instance you already run.

  • An always-on NAS or host where Private Server serves internal HTTP on port 7080.
  • A domain or subdomain you control, such as note.example.com.
  • At least one inbound route: public IPv4, globally routable IPv6, or both.
  • Administrator access to the router and NAS firewall, plus Caddy, Nginx Proxy Manager, or another TLS reverse proxy.
  • A certificate from a public CA. Production clients reject ordinary LAN HTTP; never disable certificate or hostname validation.
  • For Web access, the Private Server must allow the Web page’s exact origin through CORS.
Reserve the NAS address first.

Give the NAS a DHCP reservation. A port-forwarding rule aimed at a changing LAN address will eventually break.

03

Check IPv4, IPv6, and CGNAT

Future Direct will not ask people to choose an “IPv4 mode” or “IPv6 mode.” It will validate each route independently and publish only what works. Apply that rule to a manual setup today.

NAS network DNS Router or firewall Outcome
Public IPv4 A Forward public TCP 443 to the NAS proxy Direct works
Public IPv6 AAAA Allow inbound TCP 443 to the NAS over IPv6 Direct works
IPv4 + IPv6 A + AAAA Allow TCP 443 on both routes Best; clients choose automatically
IPv4 behind CGNAT A cannot be verified externally No true inbound port forward No Direct; future Relay fallback
Private-only IPv6 Do not publish AAAA Address is not Internet-routable No Direct

Detect CGNAT or another NAT layer

  1. Open the router status page and note its WAN IPv4 address.
  2. Visit a trusted public-IP lookup in a browser and compare the reported IPv4 address.
  3. A WAN address inside 100.64.0.0/10, 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16 means another NAT layer or CGNAT is upstream.
  4. If the two addresses differ, also check whether an ISP modem or upstream router performs another NAT.

Ordinary port forwarding cannot cross CGNAT. Ask the ISP for a public address if available. Planned Touyu clients will try Relay when Direct times out, inbound 443 is unavailable, or the client and NAS do not share a usable IP family.

Relay is not a complete five-client path today either.

The Relay service and Private Server agent have foundations in place, but product clients are not fully connected. A CGNAT result currently means “Touyu Direct cannot be used,” not “Relay has already taken over.”

An IPv6 address is not automatically a public route

Publish only globally routable IPv6. fe80::/10 link-local and fc00::/7 ULA addresses cannot be reached from the Internet. The proxy must listen on IPv6 TCP 443, and both router and NAS firewalls must allow it. A broken AAAA record can derail certificate issuance and make dual-stack clients prefer a dead route.

04

Build today’s direct path

This is the current bring-your-own-domain route. Touyu does not edit DNS, obtain your certificate, or deliver the URL to clients for you.

1

Create DNS records only for verified routes

Use A for public IPv4, AAAA for public IPv6, and both for dual stack. Update dynamic addresses when they change. Remove any AAAA that cannot pass an external check.

2

Send public TCP 443 to the reverse proxy

For IPv4, add a router port forward. IPv6 usually has no NAT, but the router and NAS firewalls must permit inbound TCP 443. A NAS with a public address needs only its host firewall rule.

3

Terminate TLS on the NAS

Let Caddy, Nginx Proxy Manager, or the system proxy hold the certificate. A proxy running directly on the NAS uses http://127.0.0.1:7080. A containerized proxy must join the Private Server Docker network and use http://touyunote:8080. Prefer TLS-ALPN-01 or a DNS challenge so no extra public port is needed.

4

Resolve a NAS management-page conflict on 443

Keep the public port at 443, but forward it to another free NAS port where Caddy listens. The management UI and reverse proxy cannot bind the same NAS port.

5

Verify from outside the home network

Turn off phone Wi-Fi and use cellular data to check DNS, the certificate, /api/health, and /api/capabilities. A LAN-only success does not prove Internet reachability.

6

Enter the HTTPS URL in a supported client

Use an HTTPS service URL with no userinfo, query, or fragment. Changing servers changes the intended token recipient; never send a token issued for one service to another.

Works on cellular, fails at home?

Enable NAT loopback on the router, or configure split DNS so the same hostname resolves to the NAS’s LAN address at home. The hostname stays the same, so the public certificate remains valid.

05

See where data travels

A custom domain and future Touyu Direct provide discovery and connectivity. Neither turns your Private Server into a copy hosted by Touyu.

Your clientnotes + files
HTTPS :443NAS certificate
Reverse proxyinside NAS
Private Serverdata authority
  • Touyu Account handles sign-in and token issuance. It does not store note bodies.
  • With today’s custom-domain route, your DNS provider stores the records; Touyu manages neither DNS nor certificates.
  • Future Direct Registry needs only instance metadata, a random hostname, verified public addresses, and state. It does not relay note traffic.
  • The certificate private key stays in the reverse proxy volume on the NAS. Do not upload it to Touyu or your DNS provider.
  • Future Relay changes the transport route only. It still reaches the same Private Server and does not rewrite data into Public Note Server.
06

Read the setup states

Use these as manual checkpoints today. When Direct ships, its setup UI should advance through the same states automatically and must not publish DNS after a failed external validation.

Not started

No usable domain, certificate, or externally verified route.

Detecting network

Find candidate IPv4/IPv6 addresses and determine whether they are Internet-routable.

Waiting for TCP 443

DNS may be prepared, but an external connection cannot reach the NAS proxy.

Issuing certificate

Public 443 is reachable and the reverse proxy is completing its ACME challenge.

Checking service

HTTPS works; health and capabilities content still need validation.

Direct ready

At least one IP route, TLS, and both anonymous endpoints have passed.

Relay recommended

CGNAT, blocked inbound 443, or no common IP family. Product-client Relay support is still pending today.

07

Run exact checks

Replace the example hostname with your real HTTPS hostname. Both endpoints are anonymous; do not paste or send a bearer token during these checks.

Check the HTTP status and JSON

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

Both requests must return HTTP 200. The /api/health JSON shape is:

Expected health response 
{"status":"healthy","version":"..."}

status must be exactly healthy. version is the running server release and changes over time.

/api/capabilities must report contract major version 1 and the current feature set:

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

Check DNS and TCP 443

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

DNS should contain only externally verified A/AAAA routes. TcpTestSucceeded must be True. From an external network, open https://note.example.com/api/health and confirm the browser shows no certificate warning.

Confirm the internal port is not public

A TCP connection to public port 7080 must fail from outside the home network. Only the reverse proxy should reach Private Server on 7080 over the internal network.

08

Diagnose by symptom

Work from the outside in: DNS → TCP 443 → TLS → reverse proxy → API. Do not change an inner layer before the outer one passes.

Symptom Check first Action
Hostname has no address A/AAAA records and DNS TTL Correct the record and wait for cache expiry. Do not publish an unverified candidate.
TCP 443 times out WAN address, CGNAT, port forward, IPv6 firewall Repair the public inbound route. NAS settings cannot bypass CGNAT.
Certificate issuance fails Whether 443 reaches the right proxy and AAAA really works Remove broken AAAA and make sure the ACME challenge reaches the proxy that owns the hostname.
HTTPS returns 502 / 504 Proxy route to 127.0.0.1:7080 Confirm Private Server listens and the proxy uses the internal HTTP upstream.
health works, capabilities fails Proxy path rewriting and server version Forward both paths unchanged to one Private Server. Do not special-case health.
Web browser reports CORS Private Server allowed origins Add the exact Web page origin. Never combine credentials with an allow-all origin.
Works outside, fails at home NAT loopback or local DNS Enable NAT loopback or use split DNS for the NAS LAN address.
IPv6 clients fail intermittently AAAA, IPv6 listener, and firewall Test from external IPv6. Remove AAAA until it passes; retain healthy IPv4.
09

Keep the boundary safe

Publishing Private Server does not mean publishing the NAS management plane. Expose only the minimum entry point required for HTTPS direct access.

  • Expose only public TCP 443. Never publish 7080, databases, file shares, or NAS management ports.
  • Never disable TLS certificate, hostname, or redirect-origin validation to make a check pass.
  • Never place usernames, passwords, tokens, or other userinfo in the URL.
  • Give DNS API credentials access only to the required zone. Future official Direct will not ask a NAS to hold Touyu primary-domain credentials.
  • Keep the NAS, reverse proxy, and Private Server updated. Back up data and certificate volumes independently.
  • When retiring an instance or domain, delete DNS records, revoke device tokens, and stop listening for the old hostname.
  • Trust availability notices only from note.touyuapp.com. There is no official Direct download or one-click binding page today.
“Expose 7080 first and debug later” is unsafe advice.

Health and capabilities must pass through the same HTTPS 443 reverse proxy. Bypassing it skips the TLS and network boundary you actually need to prove.