Skip to content

Serve:補齊 CLI 參考頁缺漏(PROXY protocol、自簽憑證後端、app capabilities) - #208

Merged
shyuan merged 2 commits into
mainfrom
serve-cli-reference-gaps
Oct 30, 2026
Merged

shyuan merged 2 commits into
mainfrom
serve-cli-reference-gaps

Conversation

@shyuan

@shyuan shyuan commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

摘要

比對官方 tailscale serve CLI 參考(2026 年 1 月 verified),站上〈Tailscale Serve〉已有大部分內容,本章節補上未涵蓋的部分。只改動 src/content/docs/features/serve.mdx 一檔。

新增

  • 範例三:HTTPS 後端與自簽憑證 — 本機服務自己上 HTTPS 時的 target 寫法:合法憑證用 https://localhost:8443、自簽憑證用 https+insecure://localhost:8443;說明 https+insecure 只跳過 Serve 對後端的憑證檢查、對外仍是 tailnet 正式憑證,並提醒 scheme 不能省(否則會被當成純 HTTP 目標)。
  • 讓 TCP 後端看到原始來源 IP:PROXY protocol — --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。
  • 「Serve 是什麼」target 條目與身分標頭段落各補一句新內容的指引。
  • 參考資料:舊 kb/### 連結換成新版官方網址(/docs/features/tailscale-serve、/docs/reference/tailscale-cli/serve、/docs/reference/examples/serve、/docs/features/tailscale-funnel,皆已實際確認可達),新增官方範例集。

本機檢查

檢查 結果
prettier 格式一致
lint:text(autocorrect) 無問題
bun run build MDX 驗證通過,96 頁產出
lint:docs 96 檔全數乾淨

對照官方 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 shyuan left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「合法憑證」這個範例實際上大多跑不通。 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

Comment thread src/content/docs/features/serve.mdx Outdated
一個 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]` 的會被拒絕(見範例一)。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

同一條 bullet 前後矛盾。 前半句說 HTTPS 後端可以寫 https:///https+insecure://(範例三),下一句卻還是「反向代理永遠轉給 http://127.0.0.1」。範例一的 Vite 段落(第 101 行)也有同樣的「永遠 http」說法。

讀者會搞不清楚哪個才對,可能為了 HTTPS 後端白白多套一層 HTTP 反代,或不相信範例三。建議改成「永遠轉給 127.0.0.1(預設走 http)」之類的寫法,兩處一起改。


Generated by Claude Code

Comment thread src/content/docs/features/serve.mdx Outdated
- `--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/)。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

這裡導向的 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

Comment thread src/content/docs/features/serve.mdx Outdated

之後凡是經由這個 Serve 的請求,使用者(或 tag 裝置)被授予的 app capability 就會以序列化 JSON 塞進 `Tailscale-App-Capabilities` 標頭,後端解析後就知道該請求帶著哪些授權;非 ASCII 內容會用 RFC 2047 Q-encoding 編碼。

和身分標頭是同一套保護:請求自帶的同名標頭會先被剝除再填入正確值,防偽原理相同。tagged 裝置也接得上:grants 有授權給 tag 的話,tag 裝置的請求同樣會帶這個標頭——身分三標頭對 tag 裝置一律空白(見 [Serve 的身分標頭](/features/serve-identity-headers/)),兩者正好互補。Funnel 的公開流量不帶這個標頭。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「一律空白」和其他地方的「不會帶」說法不同。 這裡說身分三標頭對 tag 裝置「一律空白」,但連過去的 Serve 的身分標頭(第 33 行)和本頁第 31 行都說 tagged 裝置的請求「不會帶這些標頭」。

依「空白」寫後端的人會判斷 header == "",依「不會帶」的人會檢查標頭存不存在,兩頁對同一機制的描述不一致,tag 裝置的授權 fallback 就可能寫錯。建議統一成「不會帶」。


Generated by Claude Code

Comment thread src/content/docs/features/serve.mdx Outdated
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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/content/docs/features/serve.mdx Outdated
```text
Available within your tailnet:

|-- tcp://serve-test.example.ts.net:443 (TLS terminated, PROXY protocol v2)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

範例主機名稱和全頁不一致。 這裡用 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

Comment thread src/content/docs/features/serve.mdx Outdated
|--> tcp://127.0.0.1:9899
```

注意後端那側也要有解析能力才收得下去:Caddy、HAProxy、nginx 的 stream 模組等都有對應設定;格式分 v1/v2,官方提醒大多數情況直接用 v2。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

官方連結只改了這一頁。 這頁把 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)
@shyuan

shyuan commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

感謝 review,8 條都已處理(0883c05)。逐條說明:

1. https://localhost:8443 範例(serve.mdx:162)— 重寫,並查證原始碼。 確認了 ipnlocal/serve.go:expandProxyArg 對已有 scheme 的 target 原樣保留、proxy 的 Transport 設定只有 tls.Config{InsecureSkipVerify: rp.insecure} 沒有 SNI override;ipn.ExpandProxyTargetValue 也不改寫 localhost。所以驗證名稱就是 target 寫的那一個(localhost 或 IP 127.0.0.1)——更正 reviewer 的「會改寫成 127.0.0.1」這個細節,但結論同樣成立:公開 CA 不核發這兩種 SAN,一般本機 HTTPS 後端照這個寫法就是 502。文章已改寫:明說「TLS 驗的是 target 名稱、公開 CA 不會核發 localhost/127.0.0.1 憑證」,把 https:// 限定為內部 CA/自簽涵蓋本機名稱時才走得通,一般情況指向 https+insecure://。

2. 第 19 行與範例一的矛盾說法 — 兩處都改掉「永遠轉給 http://127.0.0.1」,改為「一律連到本機迴路位址,預設按 HTTP 撥號,HTTPS 撥號見範例三」。

3. status 差異 — bullet 改寫為確切差異:掛著 Service(svc:)端點時,status 不列它們(甚至顯示 No serve config),status --json/get-config --all 才列(issued #18289 的實例正是如此)。tailscale-services.mdx:114 也補了同一句提醒,兩頁一致。

4. 「一律空白」vs「不會帶」 — 改為「不會帶身分三標頭」,與〈Serve 的身分標頭〉一致。

5–6. PROXY protocol 範例 — 補上 --bg,主機名稱改回全頁一致的 my-dev-machine.tailxxxxx.ts.net。

7. Caddy — 註明其內建 proxy_protocol listener 包裝只適用於 Caddy 自己的 HTTP listener,任意 TCP 串流前端需另裝 caddy-l4 外掛;清單保留 HAProxy、nginx stream 為原生支援。

8. 其餘頁面的舊 kb 連結 — tailscale.com/kb/1312/kb/1242/kb/1223 已全站清零(funnel.mdx、plans.mdx、webhook-dev.mdx,grep 確認 0 筆殘留),全部換成 /docs/... 新網址。

檢查:prettier、autocorrect(lint:text)、eslint、build、lint:docs 全數通過。

@shyuan
shyuan merged commit 380fc6d into main Oct 30, 2026
2 checks passed
@shyuan
shyuan deleted the serve-cli-reference-gaps branch October 30, 2026 04:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant