From bc3a07095228a5cdf1998e317e434857f4bec098 Mon Sep 17 00:00:00 2001 From: maoshen Date: Sun, 12 Apr 2026 13:38:42 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20HTTPS=20=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 详细记录使用 Tailscale 配置 HTTPS 的完整过程 - 包括安装、配置、故障排除步骤 - 提供安全考虑和高级配置说明 --- city-manual/docs/HTTPS_DEPLOYMENT.md | 465 +++++++++++++++++++++++++++ 1 file changed, 465 insertions(+) create mode 100644 city-manual/docs/HTTPS_DEPLOYMENT.md diff --git a/city-manual/docs/HTTPS_DEPLOYMENT.md b/city-manual/docs/HTTPS_DEPLOYMENT.md new file mode 100644 index 0000000..2cbf214 --- /dev/null +++ b/city-manual/docs/HTTPS_DEPLOYMENT.md @@ -0,0 +1,465 @@ +# HTTPS 部署指南 - 使用 Tailscale + +## 概述 + +本指南介绍如何使用 Tailscale 为 OpenClaw/城市手册项目配置 HTTPS 访问，实现安全的公网访问。 + +## 场景 + +- **部署环境:** LXC 容器 (10.181.143.185) +- **访问方式:** 宿主机通过 Tailscale HTTPS 访问 +- **域名:** `lobster-server.taild6528e.ts.net` +- **端口:** 18789 (OpenClaw Gateway) + +## 前提条件 + +1. LXC 容器或服务器（已安装 OpenClaw） +2. 宿主机或访问设备 +3. Tailscale 账号（免费账号即可） +4. 网络连接 + +--- + +## 步骤 1: 在 LXC 容器安装 Tailscale + +### 1.1 安装 Tailscale + +```bash +curl -fsSL https://tailscale.com/install.sh | sh +``` + +**输出示例：** +``` +Installing Tailscale for ubuntu noble, using method apt +... +Installation complete! Log in to start using Tailscale by running: +tailscale up +``` + +### 1.2 启动 Tailscale + +```bash +tailscale up +``` + +**输出：** +``` +To authenticate, visit: +https://login.tailscale.com/a/xxxxxxxxxxxxx +``` + +### 1.3 登录 Tailscale + +1. 打开浏览器访问输出的链接 +2. 使用 Google/Microsoft/GitHub 等账号登录 +3. 完成调查问卷（可选，随便选） +4. 连接设备 + +### 1.4 验证状态 + +```bash +tailscale status +``` + +**输出示例：** +``` +100.92.50.55 lobster-server phosphernew@ linux - +``` + +**说明：** +- `100.92.50.55` - Tailscale 分配的 IP +- `lobster-server` - 设备名称 +- `phosphernew@` - 账号 + +--- + +## 步骤 2: 启用 Tailscale Serve + +### 2.1 尝试启动 Serve + +```bash +tailscale serve --bg http://127.0.0.1:18789 +``` + +**可能遇到的错误：** +``` +Serve is not enabled on your tailnet. +To enable, visit: +https://login.tailscale.com/f/serve?node=nod1aN1vyE11CNTRL +``` + +### 2.2 启用 Serve 功能 + +1. 打开链接：https://login.tailscale.com/f/serve?node=nod1aN1vyE11CNTRL +2. 登录 Tailscale 管理后台 +3. 找到 "Serve" 或 "Funnel" 选项 +4. 点击 **Enable**（启用） + +### 2.3 重新启动 Serve + +```bash +tailscale serve --bg http://127.0.0.1:18789 +``` + +**成功输出：** +``` +Available within your tailnet: +https://lobster-server.taild6528e.ts.net/ +|-- proxy http://127.0.0.1:18789 + +Serve started and running in the background. +``` + +### 2.4 查看 Serve 状态 + +```bash +tailscale serve status +``` + +**输出示例：** +``` +https://lobster-server.taild6528e.ts.net (tailnet only) +|-- / proxy http://127.0.0.1:18789 +``` + +--- + +## 步骤 3: 配置 OpenClaw + +### 3.1 修改 OpenClaw 配置 + +编辑 `~/.openclaw/openclaw.json`： + +```json +{ + "gateway": { + "controlUi": { + "allowInsecureAuth": true, + "allowedOrigins": ["*"], + "dangerouslyDisableDeviceAuth": true + } + } +} +``` + +**说明：** +- `dangerouslyDisableDeviceAuth: true` - 禁用设备身份认证（内网安全环境） +- `allowedOrigins: ["*"]` - 允许所有来源（配合 Tailscale 使用） + +### 3.2 重启 Gateway + +```bash +# 停止现有进程 +pkill -f openclaw-gateway + +# 等待 2 秒 +sleep 2 + +# 重新启动 +openclaw gateway & +``` + +### 3.3 验证 Gateway 状态 + +```bash +openclaw gateway status +``` + +**输出示例：** +``` +Gateway: bind=lan (0.0.0.0), port=18789 +Dashboard: http://10.181.143.185:18789/ +``` + +--- + +## 步骤 4: 在宿主机安装 Tailscale + +### 4.1 安装 Tailscale + +在宿主机上运行： + +```bash +curl -fsSL https://tailscale.com/install.sh | sh +``` + +### 4.2 启动并登录 + +```bash +sudo tailscale up +``` + +**输出：** +``` +To authenticate, visit: +https://login.tailscale.com/a/xxxxxxxxxxxxx +``` + +### 4.3 使用同一账号登录 + +1. 打开链接 +2. **重要：** 使用与 LXC 容器**相同的账号**登录 +3. 完成认证 + +### 4.4 验证连接 + +```bash +tailscale status +``` + +**输出示例：** +``` +100.92.50.55 lobster-server phosphernew@ linux - +100.93.45.67 phospher-openclaw phosphernew@ linux - +``` + +**说明：** 两台设备在同一个 Tailscale 网络中 + +--- + +## 步骤 5: 访问 OpenClaw + +### 5.1 获取访问地址 + +从步骤 2.3 的输出中获取 HTTPS 地址： + +``` +https://lobster-server.taild6528e.ts.net +``` + +### 5.2 在浏览器访问 + +1. 打开浏览器 +2. 访问：`https://lobster-server.taild6528e.ts.net` +3. 输入网关令牌（从配置文件获取） + +### 5.3 获取网关令牌 + +```bash +grep -o '"token": "[^"]*"' ~/.openclaw/openclaw.json | cut -d'"' -f4 +``` + +**输出示例：** +``` +3f944c723dde233d333da5d46be4f6c99b604cb9f6302bef +``` + +### 5.4 连接成功 + +输入令牌后，应该能看到 OpenClaw Control UI 界面。 + +--- + +## 步骤 6: 启用公网访问（可选） + +如果需要从**任何地方**访问（不仅限于 Tailscale 网络），可以启用 Funnel。 + +### 6.1 启用 Funnel + +```bash +tailscale funnel --bg 18789 +``` + +**可能遇到的错误：** +``` +Funnel is not enabled on your tailnet. +To enable, visit: +https://login.tailscale.com/f/funnel?node=nod1aN1vyE11CNTRL +``` + +### 6.2 启用 Funnel 功能 + +1. 打开链接：https://login.tailscale.com/f/funnel?node=nod1aN1vyE11CNTRL +2. 登录管理后台 +3. 启用 Funnel 功能 + +### 6.3 重新启动 Funnel + +```bash +tailscale funnel --bg 18789 +``` + +**成功输出：** +``` +Available on the internet: +https://lobster-server.taild6528e.ts.net +``` + +### 6.4 验证状态 + +```bash +tailscale serve status +``` + +**输出示例：** +``` +# Funnel on: +# - https://lobster-server.taild6528e.ts.net + +https://lobster-server.taild6528e.ts.net (Funnel on) +|-- / proxy http://127.0.0.1:18789 +``` + +**说明：** `(Funnel on)` 表示可以从公网访问 + +--- + +## 故障排除 + +### 问题 1: DNS 解析失败 + +**错误：** `DNS_PROBE_FINISHED_NXDOMAIN` + +**原因：** Tailscale 域名只能在安装了 Tailscale 的设备上解析 + +**解决方案：** +1. 在访问设备上安装 Tailscale +2. 登录同一账号 +3. 再访问域名 + +### 问题 2: Serve 未启用 + +**错误：** `Serve is not enabled on your tailnet` + +**解决方案：** +1. 访问启用链接 +2. 在管理后台启用 Serve +3. 重新启动 serve 命令 + +### 问题 3: 设备认证失败 + +**错误：** `control ui requires device identity` + +**解决方案：** +1. 修改 `openclaw.json` 配置 +2. 添加 `"dangerouslyDisableDeviceAuth": true` +3. 重启 Gateway + +### 问题 4: 连接被拒绝 + +**错误：** `Connection refused` + +**检查：** +```bash +# 检查 Gateway 是否运行 +openclaw gateway status + +# 检查端口监听 +ss -tlnp | grep 18789 + +# 检查 Tailscale 状态 +tailscale status +``` + +### 问题 5: 令牌无效 + +**错误：** `Invalid token` + +**解决方案：** +1. 重新获取令牌 +2. 检查配置文件 +3. 重启 Gateway + +--- + +## 安全考虑 + +### 优点 + +1. **自动 HTTPS:** Tailscale 自动处理证书，无需手动配置 +2. **设备认证:** 只有 Tailscale 网络内的设备可以访问 +3. **零配置:** 无需开放防火墙端口 +4. **动态 DNS:** 域名自动更新，无需固定 IP + +### 注意事项 + +1. **账号安全:** 保护好 Tailscale 账号 +2. **设备管理:** 定期检查已连接设备 +3. **访问控制:** 使用 `dangerouslyDisableDeviceAuth` 仅限内网 +4. **Funnel 风险:** 启用 Funnel 后公网可访问，谨慎使用 + +--- + +## 高级配置 + +### 自定义域名 + +如果有自己的域名，可以配置 CNAME： + +``` +CNAME lobster-server.taild6528e.ts.net +``` + +### 多端口代理 + +```bash +# 代理多个服务 +tailscale serve --bg https://443 http://127.0.0.1:18789 +tailscale serve --bg https://8443 http://127.0.0.1:8080 +``` + +### 路径路由 + +```bash +# 不同路径代理到不同服务 +tailscale serve --bg /api http://127.0.0.1:8000 +tailscale serve --bg /chat http://127.0.0.1:18789 +``` + +--- + +## 常用命令 + +### Tailscale 管理 + +```bash +# 查看状态 +tailscale status + +# 查看 IP +tailscale ip + +# 查看 Serve 状态 +tailscale serve status + +# 停止 Serve +tailscale serve --https=443 off + +# 重启 Tailscale +sudo systemctl restart tailscaled +``` + +### OpenClaw 管理 + +```bash +# 查看状态 +openclaw status + +# 查看 Gateway 状态 +openclaw gateway status + +# 重启 Gateway +openclaw gateway restart + +# 查看日志 +openclaw logs --follow +``` + +--- + +## 参考链接 + +- [Tailscale 官方文档](https://tailscale.com/docs) +- [Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) +- [OpenClaw 文档](https://docs.openclaw.ai) +- [城市手册项目](http://10.2.0.100:8989/mashen/chengshishouce.git) + +--- + +## 版本信息 + +- **文档版本:** 1.0 +- **创建日期:** 2026-04-12 +- **Tailscale 版本:** 1.96.4 +- **OpenClaw 版本:** 2026.4.11 +- **作者:** 码神 ⚡