Repository navigation
Serve:補齊 CLI 參考頁缺漏(PROXY protocol、自簽憑證後端、app capabilities) - #208
Conversation
對照官方 tailscale serve CLI 參考(2026 年 1 月 validated)補上站上未涵蓋的內容: - 新增範例三:HTTPS 後端 target(合法憑證 https://、自簽 https+insecure://) - 新增 PROXY protocol 一節:--proxy-protocol 搭配 --tls-terminated-tcp, 後端需另有解析能力(Caddy/HAProxy/nginx stream) - 新增 Tailscale-App-Capabilities 標頭一節:v1.92+、--accept-app-caps、 tagged 裝置也適用、與身分標頭同源的剝除防偽 - 常用指令補 status/status --json 資訊差異(issue #18289)與 Services 用 get-config --all - 交代 --tun(細節指向 Tailscale Services 一篇)與 --yes - 參考資料:舊 kb/ 連結換成新官方網址,新增官方範例集 檢查:prettier、autocorrect(lint:text)、build、lint:docs 全數通過。
shyuan
left a comment
There was a problem hiding this comment.
Code review(high)共 8 項,依嚴重程度排序,詳見各行 inline comment。最需要先處理的是範例三「合法憑證」的 https://localhost:8443 寫法:Serve 轉給 127.0.0.1,公開憑證驗不過,結果會是 502。其次是第 19 行同一條 bullet 前後矛盾(「永遠轉給 http://」對上可以用 HTTPS 後端)。
Generated by Claude Code
|
|
||
| ```bash | ||
| # 本機服務用合法憑證(例如 Let's Encrypt 自動續簽的那種) | ||
| tailscale serve --bg https://localhost:8443 |
There was a problem hiding this comment.
「合法憑證」這個範例實際上大多跑不通。 Serve 只接受 localhost/127.0.0.1 目標,轉發時會把 host 改寫成 127.0.0.1,所以後端憑證是拿 127.0.0.1 去比對的。
情境:後端用的是 nas.example.com 的 Let's Encrypt 憑證,讀者照文章跑 tailscale serve --bg https://localhost:8443,Serve 連到 https://127.0.0.1:8443,憑證沒有 127.0.0.1 的 SAN,驗證失敗,tailnet 用戶端拿到 502。公開 CA 不會發 127.0.0.1 的憑證,所以本機後端實務上只有 https+insecure:// 能用,文章卻把嚴格驗證寫成常規做法。建議改寫說明,或明講這種寫法只在憑證涵蓋 127.0.0.1/localhost 時才有效。
Generated by Claude Code
| 一個 Serve 目標(target)可以是以下四種: | ||
|
|
||
| - **本機服務**:連接埠號碼(如 `3000`)、`localhost:3000`,或完整 URL。最常用來分享開發中的網站。注意反向代理永遠轉給 `http://127.0.0.1`,本機服務必須聽在 IPv4 迴路位址,只聽 `[::1]` 的會被拒絕(見範例一)。 | ||
| - **本機服務**:連接埠號碼(如 `3000`)、`localhost:3000`,或完整 URL(後端自己上了 HTTPS 就寫 `https://`/`https+insecure://` 開頭的完整 URL,見範例三)。最常用來分享開發中的網站。注意反向代理永遠轉給 `http://127.0.0.1`,本機服務必須聽在 IPv4 迴路位址,只聽 `[::1]` 的會被拒絕(見範例一)。 |
There was a problem hiding this comment.
同一條 bullet 前後矛盾。 前半句說 HTTPS 後端可以寫 https:///https+insecure://(範例三),下一句卻還是「反向代理永遠轉給 http://127.0.0.1」。範例一的 Vite 段落(第 101 行)也有同樣的「永遠 http」說法。
讀者會搞不清楚哪個才對,可能為了 HTTPS 後端白白多套一層 HTTP 反代,或不相信範例三。建議改成「永遠轉給 127.0.0.1(預設走 http)」之類的寫法,兩處一起改。
Generated by Claude Code
| - `--bg` 會把設定寫進節點的 serve config 並持續生效;沒加 `--bg` 的前景分享在重開機或 `tailscale down/up` 後要手動重跑。 | ||
| - 關閉單一分享時,`off` 指令的旗標要和當初啟用時一致。`--bg` 輸出的最後一行會直接告訴你該跑哪一行 `off` 指令,建議先跑 `tailscale serve status` 確認連接埠與路徑再關。 | ||
| - `reset` 不會印出任何訊息,跑完用 `status` 確認,會顯示 `No serve config`。注意它連 Funnel 的監聽設定也會一起清掉。 | ||
| - `status` 與 `status --json` 目前列出的內容並不相同(官方記錄在 [GitHub issue #18289](https://github.com/tailscale/tailscale/issues/18289)),要列出掛在本機的 Service 設定,用 `tailscale serve get-config --all`,細節見 [Tailscale Services](/features/tailscale-services/)。 |
There was a problem hiding this comment.
這裡導向的 Tailscale Services 頁面跟本段說法衝突。 這條 bullet 說 status 和 status --json 列出的內容不同,請讀者看 Tailscale Services 的細節,但那一頁完全沒提這個問題,反而建議用 tailscale serve status --json 檢查設定(tailscale-services.mdx:114)。
讀者點過去想看 issue #18289 的說明,看到的卻是這裡正在提醒的那個指令。另外這條 bullet 也沒說是哪一個指令漏列了什麼。建議寫清楚差異,並同步更新 tailscale-services.mdx。
Generated by Claude Code
|
|
||
| 之後凡是經由這個 Serve 的請求,使用者(或 tag 裝置)被授予的 app capability 就會以序列化 JSON 塞進 `Tailscale-App-Capabilities` 標頭,後端解析後就知道該請求帶著哪些授權;非 ASCII 內容會用 RFC 2047 Q-encoding 編碼。 | ||
|
|
||
| 和身分標頭是同一套保護:請求自帶的同名標頭會先被剝除再填入正確值,防偽原理相同。tagged 裝置也接得上:grants 有授權給 tag 的話,tag 裝置的請求同樣會帶這個標頭——身分三標頭對 tag 裝置一律空白(見 [Serve 的身分標頭](/features/serve-identity-headers/)),兩者正好互補。Funnel 的公開流量不帶這個標頭。 |
There was a problem hiding this comment.
「一律空白」和其他地方的「不會帶」說法不同。 這裡說身分三標頭對 tag 裝置「一律空白」,但連過去的 Serve 的身分標頭(第 33 行)和本頁第 31 行都說 tagged 裝置的請求「不會帶這些標頭」。
依「空白」寫後端的人會判斷 header == "",依「不會帶」的人會檢查標頭存不存在,兩頁對同一機制的描述不一致,tag 裝置的授權 fallback 就可能寫錯。建議統一成「不會帶」。
Generated by Claude Code
| HTTP 後端能從身分標頭知道連線是誰(見上方說明與 [Serve 的身分標頭](/features/serve-identity-headers/)),但 `--tcp` 轉發的是不解析內容的 TCP 連線,後端只會看到一條來自 `127.0.0.1` 的連線,無從得知真正的對端。加上 `--proxy-protocol` 之後,Serve 會在每條轉發連線的開頭插入來源 IP 與連接埠資訊,後端解析後就能還原連線者,適合有 IP 白名單或要保留連線紀錄的後端: | ||
|
|
||
| ```bash | ||
| tailscale serve --proxy-protocol=2 --tls-terminated-tcp=443 tcp://127.0.0.1:9899 |
There was a problem hiding this comment.
PROXY protocol 範例少了 --bg。 本頁其他範例都有 --bg,下面的範例輸出也不像前景執行(沒有 Press Ctrl+C to exit.)。
讀者照抄會得到前景分享,關掉終端機、重開機或 tailscale down/up 後就消失(本頁第 75 行自己也提醒過),PROXY protocol 後端會無聲無息地收不到流量。建議改成 tailscale serve --bg --proxy-protocol=2 --tls-terminated-tcp=443 tcp://127.0.0.1:9899。
Generated by Claude Code
| ```text | ||
| Available within your tailnet: | ||
|
|
||
| |-- tcp://serve-test.example.ts.net:443 (TLS terminated, PROXY protocol v2) |
There was a problem hiding this comment.
範例主機名稱和全頁不一致。 這裡用 serve-test.example.ts.net,本頁其他地方都是 my-dev-machine.tailxxxxx.ts.net;example.ts.net 也不符合 tailnet DNS 名稱的 tailXXXX.ts.net 格式。建議改成 my-dev-machine.tailxxxxx.ts.net,以免讀者以為這段輸出來自不同的環境或命名規則。
Generated by Claude Code
| |--> tcp://127.0.0.1:9899 | ||
| ``` | ||
|
|
||
| 注意後端那側也要有解析能力才收得下去:Caddy、HAProxy、nginx 的 stream 模組等都有對應設定;格式分 v1/v2,官方提醒大多數情況直接用 v2。 |
There was a problem hiding this comment.
Caddy 原生不能在純 TCP 上解析 PROXY protocol。 Caddy 內建的 proxy_protocol listener wrapper 只用在 HTTP server;要在任意 TCP 串流上解析 PROXY header,得另外裝第三方的 caddy-l4 外掛。
如果讀者的非 HTTP TCP 服務用 --tcp 加 --proxy-protocol,前面放一般的 Caddy,PROXY header 會原封不動丟給應用程式變成亂碼,或整個設定失敗。建議註明需要 caddy-l4,或把 Caddy 從清單拿掉。
Generated by Claude Code
| --- | ||
|
|
||
| 本機跑了一個開發中的網站、後台或靜態檔案,想讓同一 tailnet 裡的其他裝置連進來,又不想開防火牆連接埠或上傳到公開主機,就用 [Tailscale Serve](https://tailscale.com/kb/1312/serve)。 | ||
| 本機跑了一個開發中的網站、後台或靜態檔案,想讓同一 tailnet 裡的其他裝置連進來,又不想開防火牆連接埠或上傳到公開主機,就用 [Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve)。 |
There was a problem hiding this comment.
官方連結只改了這一頁。 這頁把 kb/1312/kb/1242/kb/1223 換成 tailscale.com/docs/...,但其他頁面還在用舊的 kb 網址(例如 use-cases/webhook-dev.mdx:200-201、getting-started/plans.mdx:118)。
如果 kb 網址哪天不再轉址,那些頁面會壞,而且全站對同一份官方文件引用兩種網址。建議 grep kb/1312、kb/1242、kb/1223,一次全部改掉(或另開 PR 處理)。
Generated by Claude Code
- 範例三改寫:說明 https:// 的 TLS 驗證名稱是 target 本身 (localhost/127.0.0.1),公開 CA 不核發這些 SAN,一般本機 HTTPS 後端應用 https+insecure://(對照 serve.go 的 expandProxyArg 與 Transport 設定) - 「永遠轉給 http://127.0.0.1」的矛盾說法移除(第 19 行、範例一) - status 與 status --json 的差異寫清楚:status 不列 Service 端點 (issue #18289),並同步在 tailscale-services.mdx 補註 - 「一律空白」改為「不會帶」,跟身分標頭頁一致 - PROXY protocol 範例補 --bg、主機名稱改回全頁一致的 my-dev-machine.tailxxxxx.ts.net - Caddy 註明其 proxy_protocol 只能用在自家 HTTP listener, 任意 TCP 串流需 caddy-l4 外掛 - 其餘頁面的舊 kb/1312/kb/1242/kb/1223 連結一次換新 (funnel、plans、webhook-dev)
|
感謝 review,8 條都已處理(0883c05)。逐條說明: 1. 2. 第 19 行與範例一的矛盾說法 — 兩處都改掉「永遠轉給 3. 4. 「一律空白」vs「不會帶」 — 改為「不會帶身分三標頭」,與〈Serve 的身分標頭〉一致。 5–6. PROXY protocol 範例 — 補上 7. Caddy — 註明其內建 8. 其餘頁面的舊 kb 連結 — 檢查:prettier、autocorrect(lint:text)、eslint、build、lint:docs 全數通過。 |
摘要
比對官方
tailscale serveCLI 參考(2026 年 1 月 verified),站上〈Tailscale Serve〉已有大部分內容,本章節補上未涵蓋的部分。只改動src/content/docs/features/serve.mdx一檔。新增
https://localhost:8443、自簽憑證用https+insecure://localhost:8443;說明https+insecure只跳過 Serve 對後端的憑證檢查、對外仍是 tailnet 正式憑證,並提醒 scheme 不能省(否則會被當成純 HTTP 目標)。--proxy-protocol=2搭配--tls-terminated-tcp的官方範例與輸出;後端側需有解析能力(Caddy/HAProxy/nginx stream module),並對照 HTTP 側已有身分標頭、此招用於 TCP 轉發。Tailscale-App-Capabilities標頭 — v1.92+ 的--accept-app-caps:grants 宣告 app capability、Serve 轉發為序列化 JSON 標頭(RFC 2047 編碼)、捨棄防偽機制與「身分標頭」相同、tagged 裝置也適用(正好框補身分三標頭對 tag 空白的缺口)。小修補
status/status --json回傳內容不同(官方 issue #18289)、Service 設定改用get-config --all。--tun(一句話帶過,細節指向〈Tailscale Services〉已有的 L3 說明,不重複)、--yes。kb/###連結換成新版官方網址(/docs/features/tailscale-serve、/docs/reference/tailscale-cli/serve、/docs/reference/examples/serve、/docs/features/tailscale-funnel,皆已實際確認可達),新增官方範例集。本機檢查
prettierlint:text(autocorrect)bun run buildlint:docs