# 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
- **作者:** 码神 ⚡