愚蠢的地球人

Headscale 官方原生并没有提供内置的后台管理界面。官方只专注于开发高性能的命令行工具和控制层服务。 不过，得益于 Headscale 提供了完善的 REST API，开源社区开发了多款优秀的第三方网页管理后台。

Headplane 是目前社区中最受推崇、维护也最活跃的 Web UI 之一。以上这些创建用户、审批客户端、创建预登录密钥、审批路由等操作都可以在 Headplane 的图形化的管理界面（Web UI）中完成。

同样的，Headplane 原生也是针对 Linux 环境设计的，不过它是用 Node.js 编写的，理论上也可以在 Windows 上编译运行。以下是我经过踩坑总结出来的编辑教程：

先安装 Node.js 的 Windows 版本，然后下载 Headplane 的源代码。

Headplane 官方使用 pnpm 管理依赖。运行以下命令安装：

npm install -g pnpm

在 C:\headplane 目录下，运行 pnpm 自动下载并安装所有前端与后端依赖组件：

pnpm install

install 过程中会有一些警告，基本上都是一些可选的依赖组件安装失败了，不影响正常使用，可以忽略。

安装完成后，运行以下命令编译前端和后端代码：

pnpm build

编译完成后在 C:\headplane\build 目录下会生成前端和后端的编译结果。

先在 headscale 里面创建一个 API_KEY 供 Headplane 使用：

.\headscale.exe apikeys create

然后在 C:\headplane 根目录下，新建一个名为 config.yaml 的文件，写入以下基础配置内容：

server:
  host: "127.0.0.1"
  port: 3003
  base_url: "https://headscale.myhost.com"
  cookie_secret: "abcdefghijklmnopqrstuvwxyz123456"
  cookie_secure: true
  cookie_max_age: 86400
  cookie_domain: "headscale.myhost.com"
  data_path: "./data"
headscale:
  url: "https://myhost.com:8080"
  public_url: "https://myhost.com:8080"
  config_path: "C:/Headscale/config.yaml"
  api_key: "hskey-api-xxxxxxxx"
  config_strict: false
integration:
  agent:
    enabled: false
    pre_authkey: ""
  docker:
    enabled: false
    container_label: "me.tale.headplane.target=headscale"
    socket: "unix:///var/run/docker.sock"
  kubernetes:
    enabled: false
    validate_manifest: true
    pod_name: "headscale"
  proc:
    enabled: false

输入以下命令运行服务：

$env:HEADPLANE_CONFIG_PATH="$PWD\config.yaml"
node build/server/index.js

如果在运行之后报错，找到错误提示，按照提示修改代码，直到能够成功运行。

我在运行过程中遇到了两个错误，分别是：

1. 在 hp-agent.ts 文件中，使用了 getegid 和 geteuid 这两个函数来获取当前进程的用户和组 ID，这两个函数在 Windows 上是不存在的，所以需要修改代码来兼容 Windows。

2. 在 index.ts 文件中，使用了 drizzle 函数来创建数据库连接，传入的参数是一个文件路径，但是在 Windows 上需要将文件路径转换为 URL 格式才能正常使用，所以需要修改代码来兼容 Windows。

我是先修改了两处源代码：

// 编辑文件 /app/server/hp-agent.ts
///将原来的代码：
import { getegid, geteuid } from 'node:process';
// 替换为：
import process from 'node:process';
const getegid = process.getegid ? process.getegid : () => 0;
const geteuid = process.geteuid ? process.geteuid : () => 0;

// 编辑文件 /app/server/index.ts
// 在文件顶部引入 pathToFileURL：
import { pathToFileURL } from 'node:url';
// 找到 createDbClient 函数，将原来的：
const db = drizzle(`file://${realPath}`);
// 替换为：
const dbUrl = pathToFileURL(realPath).toString();
const db = drizzle(dbUrl);

修改完成后重新编译，再运行就没有报错了。

浏览器访问 http://localhost:3003/admin 进入 Headplane 的登录界面，输入之前创建的 API_KEY 点登录就可以进入到管理界面了。

如果需要远程访问，可以在IIS上设置反向代理，将外部访问的请求转发到 http://localhost:3003 上，这样就可以通过 https://headscale.yourhost.com 来访问 Headplane 的管理界面了。

IIS反向代理规则：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="Headplane" stopProcessing="true">
                    <match url="^(.*)$" />
                    <action type="Rewrite" url="http://localhost:3003/{R:1}" />
                    <serverVariables>
                        <set name="HTTP_X_FORWARDED_PROTO" value="https" />
                    </serverVariables>
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>