mirror of
https://github.com/juanfont/headscale.git
synced 2025-08-14 13:51:01 +02:00
📝 Update documentation to support i18n, add Chinese.
This commit is contained in:
afterow
parent
b6fbd37539
commit
11b1617c1e
@ -1,3 +0,0 @@
|
||||
{%
|
||||
include-markdown "../../CONTRIBUTING.md"
|
||||
%}
|
||||
3
docs/en/about/contributing.md
Normal file
3
docs/en/about/contributing.md
Normal file
@ -0,0 +1,3 @@
|
||||
{%
|
||||
include-markdown "../../../CONTRIBUTING.md"
|
||||
%}
|
||||
@ -35,12 +35,12 @@ Please be aware that there are a number of reasons why we might not accept speci
|
||||
## Do you support Y method of deploying headscale?
|
||||
|
||||
We currently support deploying headscale using our binaries and the DEB packages. Visit our [installation guide using
|
||||
official releases](../setup/install/official.md) for more information.
|
||||
official releases](../../zh/setup/install/official.md) for more information.
|
||||
|
||||
In addition to that, you may use packages provided by the community or from distributions. Learn more in the
|
||||
[installation guide using community packages](../setup/install/community.md).
|
||||
[installation guide using community packages](../../zh/setup/install/community.md).
|
||||
|
||||
For convenience, we also [build Docker images with headscale](../setup/install/container.md). But **please be aware that
|
||||
For convenience, we also [build Docker images with headscale](../../zh/setup/install/container.md). But **please be aware that
|
||||
we don't officially support deploying headscale using Docker**. On our [Discord server](https://discord.gg/c84AZQhmpx)
|
||||
we have a "docker-issues" channel where you can ask for Docker-specific help to the community.
|
||||
|
||||
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
@ -8,7 +8,7 @@ hide:
|
||||
|
||||
Headscale is an open source, self-hosted implementation of the Tailscale control server.
|
||||
|
||||
This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
|
||||
This page contains the documentation for the latest version of headscale. Please also check our [FAQ](about/faq.md).
|
||||
|
||||
Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat and community support.
|
||||
|
||||
@ -1,19 +1,19 @@
|
||||
# DNS
|
||||
|
||||
Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS related settings can be configured
|
||||
within `dns` section of the [configuration file](./configuration.md).
|
||||
within `dns` section of the [configuration file](configuration.md).
|
||||
|
||||
## Setting extra DNS records
|
||||
|
||||
Headscale allows to set extra DNS records which are made available via
|
||||
[MagicDNS](https://tailscale.com/kb/1081/magicdns). Extra DNS records can be configured either via static entries in the
|
||||
[configuration file](./configuration.md) or from a JSON file that Headscale continuously watches for changes:
|
||||
[configuration file](configuration.md) or from a JSON file that Headscale continuously watches for changes:
|
||||
|
||||
* Use the `dns.extra_records` option in the [configuration file](./configuration.md) for entries that are static and
|
||||
* Use the `dns.extra_records` option in the [configuration file](configuration.md) for entries that are static and
|
||||
don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the
|
||||
configuration require a restart of Headscale.
|
||||
* For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are
|
||||
generated by scripts the option `dns.extra_records_path` in the [configuration file](./configuration.md) is useful.
|
||||
generated by scripts the option `dns.extra_records_path` in the [configuration file](configuration.md) is useful.
|
||||
Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects
|
||||
changes.
|
||||
|
||||
@ -4,3 +4,4 @@ mkdocs-macros-plugin~=1.3
|
||||
mkdocs-material[imaging]~=9.5
|
||||
mkdocs-minify-plugin~=0.7
|
||||
mkdocs-redirects~=1.2
|
||||
mkdocs-static-i18n
|
||||
14
docs/zh/about/clients.md
Normal file
14
docs/zh/about/clients.md
Normal file
@ -0,0 +1,14 @@
|
||||
# 客户端和操作系统支持
|
||||
|
||||
我们旨在支持所有提供的操作系统和平台上的 [**最后 10 个 Tailscale 客户端版本**](https://tailscale.com/changelog#client)。某些平台可能需要额外的配置才能与 headscale 连接。
|
||||
|
||||
| 操作系统 | 支持 headscale |
|
||||
| --------- | -------------------------------------------------------------------------------------------------- |
|
||||
| Linux | 是 |
|
||||
| OpenBSD | 是 |
|
||||
| FreeBSD | 是 |
|
||||
| Windows | 是（请参见 [文档](../usage/connect/windows.md) 和您 headscale 上的 `/windows` 以获取更多信息） |
|
||||
| Android | 是（请参见 [文档](../usage/connect/android.md) 以获取更多信息） |
|
||||
| macOS | 是（请参见 [文档](../usage/connect/apple.md#macos) 和您 headscale 上的 `/apple` 以获取更多信息） |
|
||||
| iOS | 是（请参见 [文档](../usage/connect/apple.md#ios) 和您 headscale 上的 `/apple` 以获取更多信息） |
|
||||
| tvOS | 是（请参见 [文档](../usage/connect/apple.md#tvos) 和您 headscale 上的 `/apple` 以获取更多信息） |
|
||||
3
docs/zh/about/contributing.md
Normal file
3
docs/zh/about/contributing.md
Normal file
@ -0,0 +1,3 @@
|
||||
{%
|
||||
include-markdown "../../../CONTRIBUTING.md"
|
||||
%}
|
||||
54
docs/zh/about/faq.md
Normal file
54
docs/zh/about/faq.md
Normal file
@ -0,0 +1,54 @@
|
||||
# 常见问题解答
|
||||
|
||||
## headscale 的设计目标是什么？
|
||||
|
||||
Headscale 旨在实现一个自托管的开源替代方案，作为 [Tailscale](https://tailscale.com/) 控制服务器。Headscale 的目标是为自托管者和爱好者提供一个可以用于他们项目和实验室的开源服务器。它实现了一个狭窄的范围，一个 _单一_ 的 Tailscale 网络（tailnet），适合个人使用或小型开源组织。
|
||||
|
||||
## 我该如何贡献？
|
||||
|
||||
Headscale 是“开源，认可贡献”，这意味着任何贡献都必须在提交之前与维护者讨论。
|
||||
|
||||
请参见 [贡献](contributing.md) 以获取更多信息。
|
||||
|
||||
## 为什么选择“认可贡献”作为模型？
|
||||
|
||||
两位维护者都有全职工作和家庭，我们希望避免疲惫。我们也希望避免贡献者在他们的 PR 未被接受时感到沮丧。
|
||||
|
||||
在提交 PR 之前，我们非常乐意通过电子邮件交流，或进行专门的电话会议。
|
||||
|
||||
## 功能 X 何时/为什么会被实现？
|
||||
|
||||
我们不知道。我们可能正在进行相关工作。如果您有兴趣贡献，请发布关于该功能的请求。
|
||||
|
||||
请注意，我们可能不接受特定贡献的原因有很多：
|
||||
|
||||
- 以自托管环境的方式实现该功能是不可能的。
|
||||
- 鉴于我们正在逆向工程 Tailscale 以满足自己的好奇心，我们可能会对自己实现该功能感兴趣。
|
||||
- 您没有随之发送单元测试和集成测试。
|
||||
|
||||
## 你们支持 Y 种部署 headscale 的方法吗？
|
||||
|
||||
我们目前支持使用我们的二进制文件和 DEB 包部署 headscale。有关更多信息，请访问我们的 [使用官方发布的安装指南](../setup/install/official.md)。
|
||||
|
||||
此外，您可以使用社区提供的包或发行版中的包。有关更多信息，请查看 [使用社区包的安装指南](../setup/install/community.md)。
|
||||
|
||||
为了方便起见，我们还 [构建了带有 headscale 的 Docker 镜像](../setup/install/container.md)。但 **请注意，我们不正式支持使用 Docker 部署 headscale**。在我们的 [Discord 服务器](https://discord.gg/c84AZQhmpx) 上，我们有一个“docker-issues”频道，您可以在这里向社区寻求 Docker 相关的帮助。
|
||||
|
||||
## 我应该使用哪个数据库？
|
||||
|
||||
我们推荐使用 SQLite 作为 headscale 的数据库：
|
||||
|
||||
- SQLite 设置简单，易于使用
|
||||
- 它适合 headscale 的所有用例
|
||||
- 开发和测试主要在 SQLite 上进行
|
||||
- PostgreSQL 仍然受支持，但被认为处于“维护模式”
|
||||
|
||||
headscale 项目本身不提供从 PostgreSQL 迁移到 SQLite 的工具。请查看 [相关工具文档](../ref/integration/tools.md)，以获取社区提供的迁移工具。
|
||||
|
||||
## 为什么我的反向代理与 headscale 不兼容？
|
||||
|
||||
我们不知道。我们自己不使用反向代理与 headscale，因此没有相关经验。我们有 [社区文档](../ref/integration/reverse-proxy.md) 介绍如何配置各种反向代理，并在我们的 [Discord 服务器](https://discord.gg/c84AZQhmpx) 上有一个专门的“reverse-proxy-issues”频道，您可以在这里向社区寻求帮助。
|
||||
|
||||
## 我可以在同一台机器上使用 headscale 和 tailscale 吗？
|
||||
|
||||
在同一台机器上运行 headscale，同时该机器也在 tailnet 中，可能会导致子网路由器、流量中继节点和 MagicDNS 的问题。它可能会工作，但不被支持。
|
||||
30
docs/zh/about/features.md
Normal file
30
docs/zh/about/features.md
Normal file
@ -0,0 +1,30 @@
|
||||
# 功能
|
||||
|
||||
Headscale 旨在实现一个自托管的开源替代方案，作为 Tailscale 控制服务器。Headscale 的目标是为自托管者和爱好者提供一个可以用于他们项目和实验室的开源服务器。此页面提供了 headscale 功能及其与 Tailscale 控制服务器兼容性的概述：
|
||||
|
||||
- [x] 完整的 Tailscale 功能“基础”支持
|
||||
- [x] 节点注册
|
||||
- [x] 交互式
|
||||
- [x] 预认证密钥
|
||||
- [x] [DNS](https://tailscale.com/kb/1054/dns)
|
||||
- [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
|
||||
- [x] [全局和受限名称服务器（分割 DNS）](https://tailscale.com/kb/1054/dns#nameservers)
|
||||
- [x] [搜索域](https://tailscale.com/kb/1054/dns#search-domains)
|
||||
- [x] [额外 DNS 记录（仅限 headscale）](../ref/dns.md#setting-extra-dns-records)
|
||||
- [x] [Taildrop（文件共享）](https://tailscale.com/kb/1106/taildrop)
|
||||
- [x] 路由广告（包括出口节点）
|
||||
- [x] 双栈（IPv4 和 IPv6）
|
||||
- [x] 瞬态节点
|
||||
- [x] 嵌入式 [DERP 服务器](https://tailscale.com/kb/1232/derp-servers)
|
||||
- [x] 访问控制列表（[GitHub 标签 "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D)）
|
||||
- [x] 通过 API 管理 ACL
|
||||
- [x] `autogroup:internet`
|
||||
- [ ] `autogroup:self`
|
||||
- [ ] `autogroup:member`
|
||||
* [ ] 使用单点登录（OpenID Connect）进行节点注册（[GitHub 标签 "OIDC"](https://github.com/juanfont/headscale/labels/OIDC)）
|
||||
- [x] 基本注册
|
||||
- [x] 从身份提供者更新用户资料
|
||||
- [ ] 动态 ACL 支持
|
||||
- [ ] OIDC 组不能在 ACL 中使用
|
||||
- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) （[#1040](https://github.com/juanfont/headscale/issues/1040)）
|
||||
- [ ] [Serve](https://tailscale.com/kb/1312/serve) （[#1234](https://github.com/juanfont/headscale/issues/1921)）
|
||||
5
docs/zh/about/help.md
Normal file
5
docs/zh/about/help.md
Normal file
@ -0,0 +1,5 @@
|
||||
# 获取帮助
|
||||
|
||||
加入我们的 [Discord 服务器](https://discord.gg/c84AZQhmpx) 以获取公告和社区支持。
|
||||
|
||||
请通过 [GitHub 问题](https://github.com/juanfont/headscale/issues) 报告错误。
|
||||
7
docs/zh/about/releases.md
Normal file
7
docs/zh/about/releases.md
Normal file
@ -0,0 +1,7 @@
|
||||
# 发布
|
||||
|
||||
所有 headscale 版本都可以在 [GitHub 发布页面](https://github.com/juanfont/headscale/releases) 上找到。这些版本以各种平台和架构的二进制文件、Debian 系统的包以及源代码归档的形式提供。容器镜像可在 [Docker Hub](https://hub.docker.com/r/headscale/headscale) 上获取。
|
||||
|
||||
headscale 版本的 Atom/RSS 源可在 [这里](https://github.com/juanfont/headscale/releases.atom) 找到。
|
||||
|
||||
请查看我们 [Discord 服务器](https://discord.gg/c84AZQhmpx) 上的“公告”频道，以获取有关 headscale 的新闻。
|
||||
3
docs/zh/about/sponsor.md
Normal file
3
docs/zh/about/sponsor.md
Normal file
@ -0,0 +1,3 @@
|
||||
# 赞助
|
||||
|
||||
如果您想支持 headscale 的开发，请考虑通过 [ko-fi.com/headscale](https://ko-fi.com/headscale) 进行捐赠。谢谢！
|
||||
BIN
docs/zh/images/headscale-acl-network.png
Normal file
BIN
docs/zh/images/headscale-acl-network.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
32
docs/zh/index.md
Normal file
32
docs/zh/index.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
- toc
|
||||
---
|
||||
|
||||
|
||||
# 欢迎使用 Headscale
|
||||
|
||||
Headscale 是 Tailscale 控制服务器的一个开源、自托管的实现。
|
||||
|
||||
本页包含最新版本的 Headscale 的文档。另请查看我们的 [FAQ](about/faq.md)。
|
||||
|
||||
加入我们的 [Discord 服务器](https://discord.gg/c84AZQhmpx) 进行聊天和获取社区支持。
|
||||
|
||||
## 设计目标
|
||||
|
||||
Headscale 旨在实现一个自托管的、开源的 [Tailscale](https://tailscale.com/) 控制服务器替代方案。Headscale 的目标是为自托管者和爱好者提供一个开源服务器，用于他们的项目和实验室。它实现了一个狭窄的范围，即一个 _单一的_ Tailscale 网络 (tailnet)，适合个人使用或小型开源组织。
|
||||
|
||||
## 支持 Headscale
|
||||
|
||||
请参阅 [赞助](about/sponsor.md) 以获取更多信息。
|
||||
|
||||
## 贡献
|
||||
|
||||
Headscale 是“开源，确认贡献”，这意味着任何贡献都必须在提交之前与维护者讨论。
|
||||
|
||||
请参阅 [贡献](about/contributing.md) 以获取更多信息。
|
||||
|
||||
## 关于
|
||||
|
||||
Headscale 由 [Kristoffer Dalby](https://kradalby.no/) 和 [Juan Font](https://font.eu) 维护。
|
||||
5
docs/zh/packaging/README.md
Normal file
5
docs/zh/packaging/README.md
Normal file
@ -0,0 +1,5 @@
|
||||
# 打包
|
||||
|
||||
我们使用 [nFPM](https://nfpm.goreleaser.com/) 来制作 `.deb`、`.rpm` 和 `.apk`。
|
||||
|
||||
此文件夹包含我们需要与这些发布一起打包的文件。
|
||||
52
docs/zh/packaging/headscale.systemd.service
Normal file
52
docs/zh/packaging/headscale.systemd.service
Normal file
@ -0,0 +1,52 @@
|
||||
[Unit]
|
||||
After=syslog.target
|
||||
After=network.target
|
||||
Description=headscale coordination server for Tailscale
|
||||
X-Restart-Triggers=/etc/headscale/config.yaml
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=headscale
|
||||
Group=headscale
|
||||
ExecStart=/usr/bin/headscale serve
|
||||
ExecReload=/usr/bin/kill -HUP $MAINPID
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
WorkingDirectory=/var/lib/headscale
|
||||
ReadWritePaths=/var/lib/headscale /var/run
|
||||
|
||||
AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_CHOWN
|
||||
CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_CHOWN
|
||||
LockPersonality=true
|
||||
NoNewPrivileges=true
|
||||
PrivateDevices=true
|
||||
PrivateMounts=true
|
||||
PrivateTmp=true
|
||||
ProcSubset=pid
|
||||
ProtectClock=true
|
||||
ProtectControlGroups=true
|
||||
ProtectHome=true
|
||||
ProtectHostname=true
|
||||
ProtectKernelLogs=true
|
||||
ProtectKernelModules=true
|
||||
ProtectKernelTunables=true
|
||||
ProtectProc=invisible
|
||||
ProtectSystem=strict
|
||||
RemoveIPC=true
|
||||
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
|
||||
RestrictNamespaces=true
|
||||
RestrictRealtime=true
|
||||
RestrictSUIDSGID=true
|
||||
RuntimeDirectory=headscale
|
||||
RuntimeDirectoryMode=0750
|
||||
StateDirectory=headscale
|
||||
StateDirectoryMode=0750
|
||||
SystemCallArchitectures=native
|
||||
SystemCallFilter=@chown
|
||||
SystemCallFilter=@system-service
|
||||
SystemCallFilter=~@privileged
|
||||
UMask=0077
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
88
docs/zh/packaging/postinstall.sh
Normal file
88
docs/zh/packaging/postinstall.sh
Normal file
@ -0,0 +1,88 @@
|
||||
#!/bin/sh
|
||||
# Determine OS platform
|
||||
# shellcheck source=/dev/null
|
||||
. /etc/os-release
|
||||
|
||||
HEADSCALE_EXE="/usr/bin/headscale"
|
||||
BSD_HIER=""
|
||||
HEADSCALE_RUN_DIR="/var/run/headscale"
|
||||
HEADSCALE_HOME_DIR="/var/lib/headscale"
|
||||
HEADSCALE_USER="headscale"
|
||||
HEADSCALE_GROUP="headscale"
|
||||
HEADSCALE_SHELL="/usr/sbin/nologin"
|
||||
|
||||
ensure_sudo() {
|
||||
if [ "$(id -u)" = "0" ]; then
|
||||
echo "Sudo permissions detected"
|
||||
else
|
||||
echo "No sudo permission detected, please run as sudo"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
ensure_headscale_path() {
|
||||
if [ ! -f "$HEADSCALE_EXE" ]; then
|
||||
echo "headscale not in default path, exiting..."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
printf "Found headscale %s\n" "$HEADSCALE_EXE"
|
||||
}
|
||||
|
||||
create_headscale_user() {
|
||||
printf "PostInstall: Adding headscale user %s\n" "$HEADSCALE_USER"
|
||||
useradd -s "$HEADSCALE_SHELL" -d "$HEADSCALE_HOME_DIR" -c "headscale default user" "$HEADSCALE_USER"
|
||||
}
|
||||
|
||||
create_headscale_group() {
|
||||
if command -V systemctl >/dev/null 2>&1; then
|
||||
printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
|
||||
groupadd "$HEADSCALE_GROUP"
|
||||
|
||||
printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
|
||||
usermod -a -G "$HEADSCALE_GROUP" "$HEADSCALE_USER"
|
||||
fi
|
||||
|
||||
if [ "$ID" = "alpine" ]; then
|
||||
printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
|
||||
addgroup "$HEADSCALE_GROUP"
|
||||
|
||||
printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
|
||||
addgroup "$HEADSCALE_USER" "$HEADSCALE_GROUP"
|
||||
fi
|
||||
}
|
||||
|
||||
create_run_dir() {
|
||||
printf "PostInstall: Creating headscale run directory \n"
|
||||
mkdir -p "$HEADSCALE_RUN_DIR"
|
||||
|
||||
printf "PostInstall: Modifying group ownership of headscale run directory \n"
|
||||
chown "$HEADSCALE_USER":"$HEADSCALE_GROUP" "$HEADSCALE_RUN_DIR"
|
||||
}
|
||||
|
||||
summary() {
|
||||
echo "----------------------------------------------------------------------"
|
||||
echo " headscale package has been successfully installed."
|
||||
echo ""
|
||||
echo " Please follow the next steps to start the software:"
|
||||
echo ""
|
||||
echo " sudo systemctl enable headscale"
|
||||
echo " sudo systemctl start headscale"
|
||||
echo ""
|
||||
echo " Configuration settings can be adjusted here:"
|
||||
echo " ${BSD_HIER}/etc/headscale/config.yaml"
|
||||
echo ""
|
||||
echo "----------------------------------------------------------------------"
|
||||
}
|
||||
|
||||
#
|
||||
# Main body of the script
|
||||
#
|
||||
{
|
||||
ensure_sudo
|
||||
ensure_headscale_path
|
||||
create_headscale_user
|
||||
create_headscale_group
|
||||
create_run_dir
|
||||
summary
|
||||
}
|
||||
15
docs/zh/packaging/postremove.sh
Normal file
15
docs/zh/packaging/postremove.sh
Normal file
@ -0,0 +1,15 @@
|
||||
#!/bin/sh
|
||||
# Determine OS platform
|
||||
# shellcheck source=/dev/null
|
||||
. /etc/os-release
|
||||
|
||||
if command -V systemctl >/dev/null 2>&1; then
|
||||
echo "Stop and disable headscale service"
|
||||
systemctl stop headscale >/dev/null 2>&1 || true
|
||||
systemctl disable headscale >/dev/null 2>&1 || true
|
||||
echo "Running daemon-reload"
|
||||
systemctl daemon-reload || true
|
||||
fi
|
||||
|
||||
echo "Removing run directory"
|
||||
rm -rf "/var/run/headscale.sock"
|
||||
176
docs/zh/ref/acls.md
Normal file
176
docs/zh/ref/acls.md
Normal file
@ -0,0 +1,176 @@
|
||||
|
||||
Headscale 实现了与 Tailscale.com 相同的策略 ACL，经过调整以适应自托管环境。
|
||||
|
||||
例如，在定义组时，必须使用用户（相当于 Tailscale.com 中的用户/登录信息）。
|
||||
|
||||
有关更多信息，请查看 [这篇文章](https://tailscale.com/kb/1018/acls/)。
|
||||
|
||||
在使用 ACL 时，用户边界不再适用。所有机器，无论属于哪个用户，只要 ACL 允许，就可以与其他主机进行通信。
|
||||
|
||||
## ACL 使用案例示例
|
||||
|
||||
让我们为一家小型企业构建一个示例用例（这是 ACL 最有用的地方）。
|
||||
|
||||
我们有一家公司，有一位老板、一位管理员、两名开发人员和一名实习生。
|
||||
|
||||
- **老板**应有权访问所有服务器，但不能访问用户的主机。
|
||||
- **管理员**同样应有权访问所有主机，但权限应限制在维护主机上（仅供示例）。
|
||||
- **开发人员**可以在开发主机上执行任何操作，但只能在生产主机上进行查看。
|
||||
- **实习生**只能与开发服务器进行交互。
|
||||
|
||||
此外，还有一个额外的服务器作为路由器，将 VPN 用户连接到内部网络 `10.20.0.0/16`。开发人员必须能够访问这些内部资源。
|
||||
|
||||
每个用户至少有一台设备连接到网络，我们有一些服务器：
|
||||
|
||||
- database.prod
|
||||
- database.dev
|
||||
- app-server1.prod
|
||||
- app-server1.dev
|
||||
- billing.internal
|
||||
- router.internal
|
||||
|
||||
|
||||
|
||||
## ACL 设置
|
||||
|
||||
ACL 必须使用 [huJSON](https://github.com/tailscale/hujson) 编写。
|
||||
|
||||
在 [注册服务器时](../usage/getting-started.md#register-a-node)，我们需要添加标志 `--advertise-tags=tag:<tag1>,tag:<tag2>`，注册服务器的用户必须被允许执行此操作。由于任何人都可以将标签添加到他们可以注册的服务器，因此标签的检查是在 headscale 服务器上完成的，只有有效的标签才会被应用。如果注册标签的用户被允许执行此操作，则该标签是有效的。
|
||||
|
||||
要在 Headscale 中使用 ACL，您必须编辑您的 `config.yaml` 文件。在该文件中，您会找到一个 `policy.path` 参数。该参数需要指向您的 ACL 文件。有关这些策略的编写方式的更多信息，请参见 [这里](https://tailscale.com/kb/1018/acls/)。
|
||||
|
||||
在更新 ACL 文件后，请重新加载或重启 Headscale。可以通过其 systemd 服务重新加载 Headscale（`sudo systemctl reload headscale`）或向主进程发送 SIGHUP 信号（`sudo kill -HUP $(pidof headscale)`）。Headscale 会在每次重新加载后记录 ACL 策略处理的结果。
|
||||
|
||||
以下是实现与上述相同权限的 ACL：
|
||||
|
||||
```json title="acl.json"
|
||||
{
|
||||
// groups 是具有共同范围的用户集合。用户可以属于多个组。
|
||||
// 组不能由其他组组成
|
||||
"groups": {
|
||||
"group:boss": ["boss"],
|
||||
"group:dev": ["dev1", "dev2"],
|
||||
"group:admin": ["admin1"],
|
||||
"group:intern": ["intern1"]
|
||||
},
|
||||
// tagOwners 在 tailscale 中是标签和被允许在服务器上设置该标签的人员之间的关系。
|
||||
// 这在 [这里](https://tailscale.com/kb/1068/acl-tags#defining-a-tag) 有详细的说明
|
||||
// 并在 [这里](https://tailscale.com/blog/rbac-like-it-was-meant-to-be/) 进行了阐释
|
||||
"tagOwners": {
|
||||
// 管理员可以添加生产中的服务器
|
||||
"tag:prod-databases": ["group:admin"],
|
||||
"tag:prod-app-servers": ["group:admin"],
|
||||
|
||||
// 老板可以将任何服务器标记为内部
|
||||
"tag:internal": ["group:boss"],
|
||||
|
||||
// 开发人员可以添加用于开发目的的服务器，以及管理员
|
||||
"tag:dev-databases": ["group:admin", "group:dev"],
|
||||
"tag:dev-app-servers": ["group:admin", "group:dev"]
|
||||
|
||||
// 实习生无法添加服务器
|
||||
},
|
||||
// 主机应使用其 IP 地址和子网掩码定义。
|
||||
// 要定义单个主机，请使用 /32 掩码。此处不能使用 DNS 条目，
|
||||
// 因为它们容易被通过替换其 IP 地址进行劫持。
|
||||
// 有关更多信息，请参见 https://github.com/tailscale/tailscale/issues/3800。
|
||||
"hosts": {
|
||||
"postgresql.internal": "10.20.0.2/32",
|
||||
"webservers.internal": "10.20.10.1/29"
|
||||
},
|
||||
"acls": [
|
||||
// 老板可以访问所有服务器
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:boss"],
|
||||
"dst": [
|
||||
"tag:prod-databases:*",
|
||||
"tag:prod-app-servers:*",
|
||||
"tag:internal:*",
|
||||
"tag:dev-databases:*",
|
||||
"tag:dev-app-servers:*"
|
||||
]
|
||||
},
|
||||
|
||||
// 管理员仅能访问服务器的管理端口，tcp/22
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:admin"],
|
||||
"proto": "tcp",
|
||||
"dst": [
|
||||
"tag:prod-databases:22",
|
||||
"tag:prod-app-servers:22",
|
||||
"tag:internal:22",
|
||||
"tag:dev-databases:22",
|
||||
"tag:dev-app-servers:22"
|
||||
]
|
||||
},
|
||||
|
||||
// 我们还允许管理员 ping 服务器
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:admin"],
|
||||
"proto": "icmp",
|
||||
"dst": [
|
||||
"tag:prod-databases:*",
|
||||
"tag:prod-app-servers:*",
|
||||
"tag:internal:*",
|
||||
"tag:dev-databases:*",
|
||||
"tag:dev-app-servers:*"
|
||||
]
|
||||
},
|
||||
|
||||
// 开发人员可以访问数据库服务器和应用程序服务器的所有端口
|
||||
// 他们只能查看生产环境的应用程序服务器，无法访问生产环境的数据库服务器
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:dev"],
|
||||
"dst": [
|
||||
"tag:dev-databases:*",
|
||||
"tag:dev-app-servers:*",
|
||||
"tag:prod-app-servers:80,443"
|
||||
]
|
||||
},
|
||||
// 开发人员通过路由器访问内部网络。
|
||||
// 内部网络由 HTTPS 端点和 PostgreSQL
|
||||
// 数据库服务器组成。还有一条额外的规则允许流量被转发到
|
||||
// 内部子网 10.20.0.0/16。请参见此问题
|
||||
// https://github.com/juanfont/headscale/issues/502
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:dev"],
|
||||
"dst": ["10.20.0.0/16:443,5432", "router.internal:0"]
|
||||
},
|
||||
|
||||
// 服务器应能够通过 tcp/5432 与数据库通信。数据库不应能够发起连接到
|
||||
// 应用程序服务器
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["tag:dev-app-servers"],
|
||||
"proto": "tcp",
|
||||
"dst": ["tag:dev-databases:5432"]
|
||||
},
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["tag:prod-app-servers"],
|
||||
"dst": ["tag:prod-databases:5432"]
|
||||
},
|
||||
|
||||
// 实习生仅在阅读模式下访问开发应用程序服务器
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:intern"],
|
||||
"dst": ["tag:dev-app-servers:80,443"]
|
||||
},
|
||||
|
||||
// 我们仍然需要允许内部用户之间的通信，因为没有任何东西可以保证每个用户都有
|
||||
// 自己的用户。
|
||||
{ "action": "accept", "src": ["boss"], "dst": ["boss:*"] },
|
||||
{ "action": "accept", "src": ["dev1"], "dst": ["dev1:*"] },
|
||||
{ "action": "accept", "src": ["dev2"], "dst": ["dev2:*"] },
|
||||
{ "action": "accept", "src": ["admin1"], "dst": ["admin1:*"] },
|
||||
{ "action": "accept", "src": ["intern1"], "dst": ["intern1:*"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
38
docs/zh/ref/configuration.md
Normal file
38
docs/zh/ref/configuration.md
Normal file
@ -0,0 +1,38 @@
|
||||
# 配置
|
||||
|
||||
- Headscale 从 YAML 文件加载其配置。
|
||||
- 它会在以下路径中搜索 `config.yaml`：
|
||||
- `/etc/headscale`
|
||||
- `$HOME/.headscale`
|
||||
- 当前工作目录
|
||||
- 使用命令行标志 `-c` 或 `--config` 从其他路径加载配置。
|
||||
- 使用命令：`headscale configtest` 验证配置文件。
|
||||
|
||||
!!! example "获取 [GitHub 存储库中的示例配置](https://github.com/juanfont/headscale/blob/main/config-example.yaml)"
|
||||
|
||||
始终选择与您使用的发布版本相同的 [GitHub 标签](https://github.com/juanfont/headscale/tags)，以确保您拥有正确的示例配置。`main` 分支可能包含尚未发布的更改。
|
||||
|
||||
=== "在 GitHub 上查看"
|
||||
|
||||
- 开发版：<https://github.com/juanfont/headscale/blob/main/config-example.yaml>
|
||||
- 版本 {{ headscale.version }}：<https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
|
||||
|
||||
=== "使用 `wget` 下载"
|
||||
|
||||
```shell
|
||||
# 开发版
|
||||
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
|
||||
|
||||
# 版本 {{ headscale.version }}
|
||||
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
|
||||
```
|
||||
|
||||
=== "使用 `curl` 下载"
|
||||
|
||||
```shell
|
||||
# 开发版
|
||||
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
|
||||
|
||||
# 版本 {{ headscale.version }}
|
||||
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
|
||||
```
|
||||
97
docs/zh/ref/dns.md
Normal file
97
docs/zh/ref/dns.md
Normal file
@ -0,0 +1,97 @@
|
||||
# DNS
|
||||
|
||||
Headscale 支持来自 Tailscale 的 [大多数 DNS 功能](../about/features.md)。与 DNS 相关的设置可以在 [配置文件](configuration.md) 的 `dns` 部分进行配置。
|
||||
|
||||
## 设置额外的 DNS 记录
|
||||
|
||||
Headscale 允许设置额外的 DNS 记录，这些记录可以通过 [MagicDNS](https://tailscale.com/kb/1081/magicdns) 提供。额外的 DNS 记录可以通过配置文件中的静态条目或 Headscale 持续监视其更改的 JSON 文件进行配置：
|
||||
|
||||
* 使用 [配置文件](configuration.md) 中的 `dns.extra_records` 选项来添加静态条目，这些条目在 Headscale 运行期间不会更改。这些条目在 Headscale 启动时处理，配置的更改需要重启 Headscale。
|
||||
* 对于在 Headscale 运行期间可能添加、更新或删除的动态 DNS 记录，或者由脚本生成的 DNS 记录，使用 [配置文件](configuration.md) 中的 `dns.extra_records_path` 选项。将其设置为包含 DNS 记录的 JSON 文件的绝对路径，Headscale 会在检测到更改时处理该文件。
|
||||
|
||||
一个示例用例是通过 NGINX 等反向代理在同一主机上服务多个应用，这里以 Prometheus 监控堆栈为例。这样可以通过 "http://grafana.myvpn.example.com" 优雅地访问服务，而不是使用 "http://hostname-in-magic-dns.myvpn.example.com:3000" 的主机名和端口组合。
|
||||
|
||||
!!! warning "限制"
|
||||
|
||||
当前，Tailscale [仅处理 A 和 AAAA 记录](https://github.com/tailscale/tailscale/blob/v1.78.3/ipn/ipnlocal/local.go#L4461-L4479)。
|
||||
|
||||
1. 使用可用的配置选项配置额外的 DNS 记录：
|
||||
|
||||
=== "静态条目，通过 `dns.extra_records`"
|
||||
|
||||
```yaml title="config.yaml"
|
||||
dns:
|
||||
...
|
||||
extra_records:
|
||||
- name: "grafana.myvpn.example.com"
|
||||
type: "A"
|
||||
value: "100.64.0.3"
|
||||
|
||||
- name: "prometheus.myvpn.example.com"
|
||||
type: "A"
|
||||
value: "100.64.0.3"
|
||||
...
|
||||
```
|
||||
|
||||
重启您的 Headscale 实例。
|
||||
|
||||
=== "动态条目，通过 `dns.extra_records_path`"
|
||||
|
||||
```json title="extra-records.json"
|
||||
[
|
||||
{
|
||||
"name": "grafana.myvpn.example.com",
|
||||
"type": "A",
|
||||
"value": "100.64.0.3"
|
||||
},
|
||||
{
|
||||
"name": "prometheus.myvpn.example.com",
|
||||
"type": "A",
|
||||
"value": "100.64.0.3"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Headscale 会自动获取上述 JSON 文件的更改。
|
||||
|
||||
!!! tip "注意事项"
|
||||
|
||||
* [配置文件](./configuration.md) 中的 `dns.extra_records_path` 选项需要引用包含额外 DNS 记录的 JSON 文件。
|
||||
* 如果您使用脚本生成 JSON 文件，请确保“排序键”并生成稳定输出。Headscale 使用校验和来检测文件的更改，而稳定的输出可以避免不必要的处理。
|
||||
|
||||
1. 使用您选择的 DNS 查询工具验证 DNS 记录是否正确设置：
|
||||
|
||||
=== "使用 dig 查询"
|
||||
|
||||
```shell
|
||||
dig +short grafana.myvpn.example.com
|
||||
100.64.0.3
|
||||
```
|
||||
|
||||
=== "使用 drill 查询"
|
||||
|
||||
```shell
|
||||
drill -Q grafana.myvpn.example.com
|
||||
100.64.0.3
|
||||
```
|
||||
|
||||
1. 可选：设置反向代理
|
||||
|
||||
这里的一个主要示例是能够访问同一主机上的内部监控服务，而不需要指定端口，下面是 NGINX 配置片段：
|
||||
|
||||
```nginx title="nginx.conf"
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
|
||||
server_name grafana.myvpn.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:3000;
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
45
docs/zh/ref/exit-node.md
Normal file
45
docs/zh/ref/exit-node.md
Normal file
@ -0,0 +1,45 @@
|
||||
# 出口节点
|
||||
|
||||
## 在节点上操作
|
||||
|
||||
注册节点并使其宣布自己为出口节点：
|
||||
|
||||
```console
|
||||
$ sudo tailscale up --login-server https://headscale.example.com --advertise-exit-node
|
||||
```
|
||||
|
||||
如果节点已经注册，可以通过以下命令宣布其出口能力：
|
||||
|
||||
```console
|
||||
$ sudo tailscale set --advertise-exit-node
|
||||
```
|
||||
|
||||
要将节点用作出口节点，必须在节点上启用 IP 转发。请参考官方 [Tailscale 文档](https://tailscale.com/kb/1019/subnets/?tab=linux#enable-ip-forwarding) 了解如何启用 IP 转发。
|
||||
|
||||
## 在控制服务器上操作
|
||||
|
||||
```console
|
||||
$ headscale nodes list-routes
|
||||
ID | Hostname | Approved | Available | Serving
|
||||
1 | ts-head-ruqsg8 | | 0.0.0.0/0, ::/0 |
|
||||
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
|
||||
|
||||
# 注意：对于出口节点，只需批准 IPv4 或 IPv6 路由之一，另一个会自动添加。
|
||||
$ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0
|
||||
Node updated
|
||||
|
||||
$ headscale nodes list-routes
|
||||
ID | Hostname | Approved | Available | Serving
|
||||
1 | ts-head-ruqsg8 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
|
||||
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
|
||||
```
|
||||
|
||||
## 在客户端上操作
|
||||
|
||||
现在可以使用出口节点：
|
||||
|
||||
```console
|
||||
$ sudo tailscale set --exit-node phobos
|
||||
```
|
||||
|
||||
请参考官方 [Tailscale 文档](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) 了解如何在你的设备上设置出口节点。
|
||||
139
docs/zh/ref/integration/reverse-proxy.md
Normal file
139
docs/zh/ref/integration/reverse-proxy.md
Normal file
@ -0,0 +1,139 @@
|
||||
# 在反向代理后运行 headscale
|
||||
|
||||
!!! 警告 "社区文档"
|
||||
|
||||
本页面不是 headscale 作者主动维护的，由社区成员撰写。
|
||||
**它可能已经过时，并且可能缺少必要的步骤**。
|
||||
|
||||
在反向代理后运行 headscale 是有用的，尤其是在同一服务器上运行多个应用程序时，您希望重用相同的外部 IP 和端口 - 通常是 tcp/443 用于 HTTPS。
|
||||
|
||||
### WebSockets
|
||||
|
||||
反向代理必须配置为支持 WebSockets，以便与 Tailscale 客户端进行通信。
|
||||
|
||||
当使用 headscale 嵌入的 DERP 服务器时，也需要 WebSockets 支持。在这种情况下，您还需要暴露用于 STUN 的 UDP 端口（默认情况下为 udp/3478）。请查看我们的 [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml)。
|
||||
|
||||
### Cloudflare
|
||||
|
||||
在 Cloudflare 代理或 Cloudflare 隧道后运行 headscale 不受支持，并且将无法工作，因为 Cloudflare 不支持 Tailscale 协议所需的 WebSocket POST。请参见 [此问题](https://github.com/juanfont/headscale/issues/1468)。
|
||||
|
||||
### TLS
|
||||
|
||||
可以配置 headscale 不使用 TLS，而是让反向代理处理。将以下配置值添加到您的 headscale 配置文件中。
|
||||
|
||||
```yaml title="config.yaml"
|
||||
server_url: https://<YOUR_SERVER_NAME> # 这应该是 headscale 将提供的 FQDN
|
||||
listen_addr: 0.0.0.0:8080
|
||||
metrics_listen_addr: 0.0.0.0:9090
|
||||
tls_cert_path: ""
|
||||
tls_key_path: ""
|
||||
```
|
||||
|
||||
## nginx
|
||||
|
||||
以下示例配置可用于您的 nginx 设置，根据需要替换值。`<IP:PORT>` 应该是 headscale 运行的 IP 地址和端口。在大多数情况下，这将是 `http://localhost:8080`。
|
||||
|
||||
```nginx title="nginx.conf"
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
|
||||
server_name <YOUR_SERVER_NAME>;
|
||||
|
||||
ssl_certificate <PATH_TO_CERT>;
|
||||
ssl_certificate_key <PATH_CERT_KEY>;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
|
||||
location / {
|
||||
proxy_pass http://<IP:PORT>;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
proxy_set_header Host $server_name;
|
||||
proxy_redirect http:// https://;
|
||||
proxy_buffering off;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## istio/envoy
|
||||
|
||||
如果您使用 [Istio](https://istio.io/) ingressgateway 或 [Envoy](https://www.envoyproxy.io/) 作为反向代理，以下是一些提示。如果未设置，您可能会在代理中看到以下调试日志：
|
||||
|
||||
```log
|
||||
Sending local reply with details upgrade_failed
|
||||
```
|
||||
|
||||
### Envoy
|
||||
|
||||
您需要添加一个名为 `tailscale-control-protocol` 的新 upgrade_type。[查看详细信息](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)。
|
||||
|
||||
### Istio
|
||||
|
||||
与 envoy 相同，我们可以使用 `EnvoyFilter` 来添加 upgrade_type。
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: EnvoyFilter
|
||||
metadata:
|
||||
name: headscale-behind-istio-ingress
|
||||
namespace: istio-system
|
||||
spec:
|
||||
configPatches:
|
||||
- applyTo: NETWORK_FILTER
|
||||
match:
|
||||
listener:
|
||||
filterChain:
|
||||
filter:
|
||||
name: envoy.filters.network.http_connection_manager
|
||||
patch:
|
||||
operation: MERGE
|
||||
value:
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
|
||||
upgrade_configs:
|
||||
- upgrade_type: tailscale-control-protocol
|
||||
```
|
||||
|
||||
## Caddy
|
||||
|
||||
以下 Caddyfile 是使用 Caddy 作为 headscale 的反向代理所需的所有配置，结合上面的 `config.yaml` 规范以禁用 headscale 内置的 TLS。根据需要替换值 - `<YOUR_SERVER_NAME>` 应该是 headscale 将提供的 FQDN，`<IP:PORT>` 应该是 headscale 运行的 IP 地址和端口。在大多数情况下，这将是 `localhost:8080`。
|
||||
|
||||
```none title="Caddyfile"
|
||||
<YOUR_SERVER_NAME> {
|
||||
reverse_proxy <IP:PORT>
|
||||
}
|
||||
```
|
||||
|
||||
Caddy v2 将 [自动](https://caddyserver.com/docs/automatic-https) 为您的域名/子域名提供证书，强制使用 HTTPS，并代理 WebSockets - 无需进一步配置。
|
||||
|
||||
对于稍微复杂的配置，利用 Docker 容器管理 Caddy、headscale 和 Headscale-UI，[Guru Computing 的指南](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) 是一个很好的参考。
|
||||
|
||||
## Apache
|
||||
|
||||
以下最小 Apache 配置将流量代理到 `<IP:PORT>` 上的 headscale 实例。请注意，`upgrade=any` 是 `ProxyPass` 的一个参数，以便正确转发 WebSockets 流量，其 `Upgrade` 头值不等于 `WebSocket`（即 Tailscale 控制协议）。有关更多信息，请参见 [Apache 文档](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html)。
|
||||
|
||||
```apache title="apache.conf"
|
||||
<VirtualHost *:443>
|
||||
ServerName <YOUR_SERVER_NAME>
|
||||
|
||||
ProxyPreserveHost On
|
||||
ProxyPass / http://<IP:PORT>/ upgrade=any
|
||||
|
||||
SSLEngine On
|
||||
SSLCertificateFile <PATH_TO_CERT>
|
||||
SSLCertificateKeyFile <PATH_CERT_KEY>
|
||||
</VirtualHost>
|
||||
```
|
||||
12
docs/zh/ref/integration/tools.md
Normal file
12
docs/zh/ref/integration/tools.md
Normal file
@ -0,0 +1,12 @@
|
||||
# 与 headscale 相关的工具
|
||||
|
||||
!!! 警告 "社区贡献"
|
||||
|
||||
本页面包含社区贡献。这里列出的项目不是由 headscale 作者维护，而是由社区成员撰写。
|
||||
|
||||
本页面收集与 headscale 相关的第三方工具和脚本。
|
||||
|
||||
| 名称 | 仓库链接 | 描述 |
|
||||
| --------------------- | ------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| tailscale-manager | [Github](https://github.com/singlestore-labs/tailscale-manager) | 动态管理 Tailscale |
|
||||
| headscalebacktosqlite | [Github](https://github.com/bigbozza/headscalebacktosqlite) | 将 headscale 从 PostgreSQL 迁移回 SQLite |
|
||||
20
docs/zh/ref/integration/web-ui.md
Normal file
20
docs/zh/ref/integration/web-ui.md
Normal file
@ -0,0 +1,20 @@
|
||||
|
||||
|
||||
# headscale 的 Web 界面
|
||||
|
||||
!!! 警告 "社区贡献"
|
||||
|
||||
本页面包含社区贡献。这里列出的项目不是由 headscale 作者维护，而是由社区成员撰写。
|
||||
|
||||
Headscale 不提供内置的 Web 界面，但用户可以从可用选项中选择一个。
|
||||
|
||||
| 名称 | 仓库链接 | 描述 |
|
||||
| --------------- | ------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| headscale-webui | [Github](https://github.com/ifargle/headscale-webui) | 一个简单的 headscale Web UI，适用于小规模部署。 |
|
||||
| headscale-ui | [Github](https://github.com/gurucomputing/headscale-ui) | headscale Tailscale 兼容协调服务器的 Web 前端。 |
|
||||
| HeadscaleUi | [GitHub](https://github.com/simcu/headscale-ui) | 一个静态的 headscale 管理 UI，无需后端环境。 |
|
||||
| Headplane | [GitHub](https://github.com/tale/headplane) | 一个先进的 Tailscale 灵感前端，用于 headscale。 |
|
||||
| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin) | Headscale-Admin 旨在为 headscale 提供一个简单、现代的 Web 界面。 |
|
||||
| ouroboros | [Github](https://github.com/yellowsink/ouroboros) | Ouroboros 旨在让用户管理自己的设备，而不是为管理员设计。 |
|
||||
|
||||
您可以在我们的 [Discord 服务器](https://discord.gg/c84AZQhmpx) 的 "web-interfaces" 频道中寻求支持。
|
||||
181
docs/zh/ref/oidc.md
Normal file
181
docs/zh/ref/oidc.md
Normal file
@ -0,0 +1,181 @@
|
||||
# 配置 Headscale 使用 OIDC 认证
|
||||
|
||||
为了通过集中式解决方案认证用户，需要启用 OIDC 集成。
|
||||
|
||||
已知限制：
|
||||
|
||||
- 不支持动态 ACL
|
||||
- OIDC 组不能用于 ACL
|
||||
|
||||
---
|
||||
|
||||
## 基本配置
|
||||
|
||||
在 `config.yaml` 中，根据你的需求进行配置：
|
||||
|
||||
```yaml title="config.yaml"
|
||||
oidc:
|
||||
# 在 OIDC 提供者健康且可用之前阻止启动
|
||||
only_start_if_oidc_is_available: true
|
||||
# 由 OIDC 提供者指定
|
||||
issuer: "https://your-oidc.issuer.com/path"
|
||||
# 由 OIDC 提供者指定/生成
|
||||
client_id: "your-oidc-client-id"
|
||||
client_secret: "your-oidc-client-secret"
|
||||
# 或者，使用 `client_secret_path` 从文件中读取密钥。
|
||||
# 它支持环境变量解析，便于与 systemd 的 `LoadCredential` 集成：
|
||||
#client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
|
||||
# 第三种选择是从环境变量中加载 OIDC 密钥
|
||||
# 设置 HEADSCALE_OIDC_CLIENT_SECRET 为所需的值
|
||||
|
||||
# 自定义 OIDC 流程中的范围，默认为 "openid"、"profile" 和 "email"，并添加自定义查询参数
|
||||
scope: ["openid", "profile", "email", "custom"]
|
||||
# 可选：传递给浏览器登录请求的参数，用于调整 OIDC 提供者的行为
|
||||
extra_params:
|
||||
domain_hint: example.com
|
||||
|
||||
# 可选：允许的主体域和/或用户列表。如果认证用户的域不在此列表中，认证请求将被拒绝。
|
||||
allowed_domains:
|
||||
- example.com
|
||||
# 可选。注意 Keycloak 中的组名前有 '/'。
|
||||
allowed_groups:
|
||||
- /headscale
|
||||
# 可选。
|
||||
allowed_users:
|
||||
- alice@example.com
|
||||
|
||||
# 可选：PKCE（Proof Key for Code Exchange）配置
|
||||
# PKCE 通过防止授权代码拦截攻击，为 OAuth 2.0 授权代码流程增加了额外的安全层
|
||||
# 参见 https://datatracker.ietf.org/doc/html/rfc7636
|
||||
pkce:
|
||||
# 启用或禁用 PKCE 支持（默认：false）
|
||||
enabled: false
|
||||
# 使用的 PKCE 方法：
|
||||
# - plain: 使用纯代码验证器
|
||||
# - S256: 使用 SHA256 哈希代码验证器（默认，推荐）
|
||||
method: S256
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Azure AD 示例
|
||||
|
||||
为了将 Headscale 与 Azure Active Directory 集成，我们需要配置一个具有正确范围和重定向 URI 的应用注册。以下是使用 Terraform 的示例：
|
||||
|
||||
```hcl title="terraform.hcl"
|
||||
resource "azuread_application" "headscale" {
|
||||
display_name = "Headscale"
|
||||
|
||||
sign_in_audience = "AzureADMyOrg"
|
||||
fallback_public_client_enabled = false
|
||||
|
||||
required_resource_access {
|
||||
// Microsoft Graph
|
||||
resource_app_id = "00000003-0000-0000-c000-000000000000"
|
||||
|
||||
resource_access {
|
||||
// scope: profile
|
||||
id = "14dad69e-099b-42c9-810b-d002981feec1"
|
||||
type = "Scope"
|
||||
}
|
||||
resource_access {
|
||||
// scope: openid
|
||||
id = "37f7f235-527c-4136-accd-4a02d197296e"
|
||||
type = "Scope"
|
||||
}
|
||||
resource_access {
|
||||
// scope: email
|
||||
id = "64a6cdd6-aab1-4aaf-94b8-3cc8405e90d0"
|
||||
type = "Scope"
|
||||
}
|
||||
}
|
||||
web {
|
||||
# 指向你的 Headscale 实例
|
||||
redirect_uris = ["https://headscale.example.com/oidc/callback"]
|
||||
|
||||
implicit_grant {
|
||||
access_token_issuance_enabled = false
|
||||
id_token_issuance_enabled = true
|
||||
}
|
||||
}
|
||||
|
||||
group_membership_claims = ["SecurityGroup"]
|
||||
optional_claims {
|
||||
# 暴露组成员关系
|
||||
id_token {
|
||||
name = "groups"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
resource "azuread_application_password" "headscale-application-secret" {
|
||||
display_name = "Headscale Server"
|
||||
application_object_id = azuread_application.headscale.object_id
|
||||
}
|
||||
|
||||
resource "azuread_service_principal" "headscale" {
|
||||
application_id = azuread_application.headscale.application_id
|
||||
}
|
||||
|
||||
resource "azuread_service_principal_password" "headscale" {
|
||||
service_principal_id = azuread_service_principal.headscale.id
|
||||
end_date_relative = "44640h"
|
||||
}
|
||||
|
||||
output "headscale_client_id" {
|
||||
value = azuread_application.headscale.application_id
|
||||
}
|
||||
|
||||
output "headscale_client_secret" {
|
||||
value = azuread_application_password.headscale-application-secret.value
|
||||
}
|
||||
```
|
||||
|
||||
在 Headscale 的 `config.yaml` 中配置：
|
||||
|
||||
```yaml title="config.yaml"
|
||||
oidc:
|
||||
issuer: "https://login.microsoftonline.com/<tenant-UUID>/v2.0"
|
||||
client_id: "<client-id-from-terraform>"
|
||||
client_secret: "<client-secret-from-terraform>"
|
||||
|
||||
# 可选：添加 "groups"
|
||||
scope: ["openid", "profile", "email"]
|
||||
extra_params:
|
||||
# 使用与 Azure AD 关联的域名
|
||||
domain_hint: example.com
|
||||
# 可选：强制 Azure AD 账户选择器
|
||||
prompt: select_account
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Google OAuth 示例
|
||||
|
||||
为了将 Headscale 与 Google 集成，你需要一个 [Google Cloud Console](https://console.cloud.google.com) 账户。
|
||||
|
||||
如果你需要认证来自你域名外的用户，Google OAuth 有一个[验证流程](https://support.google.com/cloud/answer/9110914?hl=en)。如果只需要认证你域名内的用户（例如 `@example.com`），则不需要通过验证流程。
|
||||
|
||||
如果你没有域名，或者需要添加域名外的用户，可以通过 Google Console 手动添加电子邮件。
|
||||
|
||||
### 步骤
|
||||
|
||||
1. 登录 [Google Console](https://console.cloud.google.com)，如果没有账户则创建一个。
|
||||
2. 创建一个项目（如果还没有）。
|
||||
3. 在左侧菜单中，转到 `APIs and services` -> `Credentials`。
|
||||
4. 点击 `Create Credentials` -> `OAuth client ID`。
|
||||
5. 在 `Application Type` 下选择 `Web Application`。
|
||||
6. 在 `Name` 中输入任意名称。
|
||||
7. 在 `Authorised redirect URIs` 中使用 `https://example.com/oidc/callback`，将 `example.com` 替换为你的 Headscale URL。
|
||||
8. 点击表单底部的 `Save`。
|
||||
9. 记下 `Client ID` 和 `Client secret`，你也可以下载以备参考。
|
||||
10. 编辑 Headscale 配置文件，在 `oidc` 部分填写 `client_id` 和 `client_secret`：
|
||||
```yaml title="config.yaml"
|
||||
oidc:
|
||||
issuer: "https://accounts.google.com"
|
||||
client_id: ""
|
||||
client_secret: ""
|
||||
scope: ["openid", "profile", "email"]
|
||||
```
|
||||
|
||||
你还可以使用 `allowed_domains` 和 `allowed_users` 来限制可以认证的用户。
|
||||
95
docs/zh/ref/remote-cli.md
Normal file
95
docs/zh/ref/remote-cli.md
Normal file
@ -0,0 +1,95 @@
|
||||
# 使用远程 CLI 控制 Headscale
|
||||
|
||||
本文件旨在向用户展示如何通过 `headscale` 命令行工具从远程计算机控制 Headscale 实例。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 一台用于运行 `headscale` 的工作站（任何支持的平台，例如 Linux）。
|
||||
- 一台启用 gRPC 的 Headscale 服务器。
|
||||
- 允许连接到 gRPC 端口（默认：`50443`）。
|
||||
- 远程访问要求通过 TLS 加密连接。
|
||||
- 一个 API 密钥用于与 Headscale 服务器进行身份验证。
|
||||
|
||||
## 创建 API 密钥
|
||||
|
||||
我们需要创建一个 API 密钥，以便在从工作站使用远程 Headscale 服务器时进行身份验证。
|
||||
|
||||
要创建 API 密钥，请登录到您的 Headscale 服务器并生成一个密钥：
|
||||
|
||||
```shell
|
||||
headscale apikeys create --expiration 90d
|
||||
```
|
||||
|
||||
复制命令的输出并为稍后保存。请注意，密钥一旦丢失无法再次检索，您需要使旧的密钥失效，并创建新的密钥。
|
||||
|
||||
要列出当前与服务器关联的密钥，请使用：
|
||||
|
||||
```shell
|
||||
headscale apikeys list
|
||||
```
|
||||
|
||||
要使密钥失效：
|
||||
|
||||
```shell
|
||||
headscale apikeys expire --prefix "<PREFIX>"
|
||||
```
|
||||
|
||||
## 下载并配置 Headscale
|
||||
|
||||
1. 从 [GitHub 的发布页面](https://github.com/juanfont/headscale/releases) 下载 [`headscale` 二进制文件](https://github.com/juanfont/headscale/releases)。确保版本与服务器上的相同。
|
||||
|
||||
2. 将二进制文件放在您的 `PATH` 中，例如 `/usr/local/bin/headscale`。
|
||||
|
||||
3. 使 `headscale` 可执行：
|
||||
|
||||
```shell
|
||||
chmod +x /usr/local/bin/headscale
|
||||
```
|
||||
|
||||
4. 通过一个最小的 YAML 配置文件或环境变量提供远程 Headscale 服务器的连接参数：
|
||||
|
||||
=== "最小 YAML 配置文件"
|
||||
|
||||
```yaml title="config.yaml"
|
||||
cli:
|
||||
address: <HEADSCALE_ADDRESS>:<PORT>
|
||||
api_key: <API_KEY_FROM_PREVIOUS_STEP>
|
||||
```
|
||||
|
||||
=== "环境变量"
|
||||
|
||||
```shell
|
||||
export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
|
||||
export HEADSCALE_CLI_API_KEY="<API_KEY_FROM_PREVIOUS_STEP>"
|
||||
```
|
||||
|
||||
!!! bug
|
||||
|
||||
Headscale 目前需要至少有一个空的配置文件才能使用环境变量指定连接详细信息。请参见 [第2193号问题](https://github.com/juanfont/headscale/issues/2193) 了解更多信息。
|
||||
|
||||
这将指示 `headscale` 二进制文件连接到位于 `<HEADSCALE_ADDRESS>:<PORT>` 的远程实例，而不是连接到本地实例。
|
||||
|
||||
5. 测试连接
|
||||
|
||||
让我们运行 Headscale 命令来验证我们是否能够通过列出节点来进行连接：
|
||||
|
||||
```shell
|
||||
headscale nodes list
|
||||
```
|
||||
|
||||
您现在应该能够从工作站看到节点列表，并可以从您的工作站控制 Headscale 服务器。
|
||||
|
||||
## 通过代理
|
||||
|
||||
可以在反向代理后运行 gRPC 远程端点，比如 Nginx，并让它运行在与 Headscale 相同的端口上。
|
||||
|
||||
虽然这不是一个受支持的功能，但 [这上面有一个在 NixOS 上如何设置的示例](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91)。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 确保服务器和工作站上运行的 Headscale 版本相同。
|
||||
- 确保允许连接到 gRPC 端口。
|
||||
- 验证您的 TLS 证书是否有效且受信任。
|
||||
- 如果您没有访问受信任证书的权限（例如 Let's Encrypt 的证书），请：
|
||||
- 将您的自签名证书添加到操作系统的信任存储中 _或_
|
||||
- 通过在配置文件中设置 `cli.insecure: true` 或通过设置环境变量 `HEADSCALE_CLI_INSECURE=1` 禁用证书验证。我们**不**推荐禁用证书验证。
|
||||
78
docs/zh/ref/tls.md
Normal file
78
docs/zh/ref/tls.md
Normal file
@ -0,0 +1,78 @@
|
||||
# 通过 TLS 运行服务（可选）
|
||||
|
||||
## 自带证书
|
||||
|
||||
Headscale 可以配置通过 TLS 暴露其网络服务。要手动配置证书和密钥文件，请设置 `tls_cert_path` 和 `tls_key_path` 配置参数。如果路径是相对的，它将被解释为相对于读取配置文件的目录。
|
||||
|
||||
```yaml title="config.yaml"
|
||||
tls_cert_path: ""
|
||||
tls_key_path: ""
|
||||
```
|
||||
|
||||
证书应包含完整的链，否则某些客户端（如 Tailscale Android 客户端）将拒绝它。
|
||||
|
||||
## Let's Encrypt / ACME
|
||||
|
||||
要通过 [Let's Encrypt](https://letsencrypt.org/) 自动获取证书，请将 `tls_letsencrypt_hostname` 设置为所需的证书主机名。此名称必须解析到 Headscale 可访问的 IP 地址（即，它必须与 `server_url` 配置参数相对应）。证书和 Let's Encrypt 账户凭据将存储在 `tls_letsencrypt_cache_dir` 中配置的目录中。如果路径是相对的，它将被解释为相对于读取配置文件的目录。
|
||||
|
||||
```yaml title="config.yaml"
|
||||
tls_letsencrypt_hostname: ""
|
||||
tls_letsencrypt_listen: ":http"
|
||||
tls_letsencrypt_cache_dir: ".cache"
|
||||
tls_letsencrypt_challenge_type: HTTP-01
|
||||
```
|
||||
|
||||
### 挑战类型
|
||||
|
||||
Headscale 仅支持两种值作为 `tls_letsencrypt_challenge_type`：`HTTP-01`（默认）和 `TLS-ALPN-01`。
|
||||
|
||||
#### HTTP-01
|
||||
|
||||
对于 `HTTP-01`，Headscale 必须在端口 80 上可访问，以便进行 Let's Encrypt 的自动验证，此外，还要配置在 `listen_addr` 中的端口。默认情况下，Headscale 在所有本地 IP 的端口 80 上监听，以进行 Let's Encrypt 的自动验证。
|
||||
|
||||
如果您需要更改 Headscale 用于 Let's Encrypt 验证过程的 IP 和/或端口，请将 `tls_letsencrypt_listen` 设置为适当的值。这在您以非 root 用户身份运行 Headscale（或无法运行 `setcap`）时很有用。然而，请记住，Let's Encrypt **仅**会连接到端口 80 进行验证回调，因此如果您更改了 `tls_letsencrypt_listen`，您还需要配置其他东西（例如防火墙规则）来将流量从端口 80 转发到 `tls_letsencrypt_listen` 中指定的 ip:port 组合。
|
||||
|
||||
#### TLS-ALPN-01
|
||||
|
||||
对于 `TLS-ALPN-01`，Headscale 在 `listen_addr` 中定义的 ip:port 组合上监听。Let's Encrypt **仅**会在端口 443 上连接以进行验证回调，因此如果 `listen_addr` 没有设置为端口 443，则需要其他配置（例如防火墙规则）以将流量从端口 443 转发到在 `listen_addr` 中指定的 ip:port 组合。
|
||||
|
||||
### 技术描述
|
||||
|
||||
Headscale 使用 [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert)库，提供 [ACME 协议](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) 验证，以 facilitar通过 [Let's Encrypt](https://letsencrypt.org/about/) 自动续订证书。证书将自动续订，您可以期待以下结果：
|
||||
|
||||
- Let’s Encrypt 提供的证书自签发之日起有效期为 3 个月。
|
||||
- 只有当证书的有效期剩余 30 天或更少时，Headscale 才会尝试续订。
|
||||
- `autocert` 的续订尝试将在 30-60 分钟的随机间隔内触发。
|
||||
- 跳过续订或续订成功时不会生成日志输出。
|
||||
|
||||
#### 检查证书过期
|
||||
|
||||
如果您想验证证书续订是否成功，可以手动检查，或通过外部监控软件进行监控。这是手动执行的两个示例：
|
||||
|
||||
1. 在您喜欢的浏览器中打开 Headscale 服务器的 URL，并手动检查收到的证书的过期日期。
|
||||
2. 或者，通过 CLI 使用 `openssl` 远程检查：
|
||||
|
||||
```bash
|
||||
$ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates
|
||||
(...)
|
||||
notBefore=2024年2月8日 09:48:26 GMT
|
||||
notAfter=2024年5月8日 09:48:25 GMT
|
||||
```
|
||||
|
||||
#### autocert 库的日志输出
|
||||
|
||||
由于这些日志行来自 autocert 库，所以并非严格由 Headscale 本身生成。
|
||||
|
||||
```plaintext
|
||||
acme/autocert: missing server name
|
||||
```
|
||||
|
||||
可能是由于一个未指定主机名的传入连接引起的，例如直接针对服务器 IP 的 `curl` 请求，或意外的主机名。
|
||||
|
||||
```plaintext
|
||||
acme/autocert: host "[foo]" not configured in HostWhitelist
|
||||
```
|
||||
|
||||
类似于上面的情况，这可能表示对错误主机名的无效传入请求，通常是仅使用 IP 本身。
|
||||
|
||||
autocert 的源代码可以在 [这里](https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.19.0:acme/autocert/autocert.go) 找到。
|
||||
51
docs/zh/setup/install/community.md
Normal file
51
docs/zh/setup/install/community.md
Normal file
@ -0,0 +1,51 @@
|
||||
# 社区提供的安装包
|
||||
|
||||
一些 Linux 发行版和社区成员为 Headscale 提供了安装包。这些包可以作为 Headscale 维护者提供的 [官方版本](official.md) 的替代方案。这些包通常能更好地集成到目标操作系统中，并且通常会：
|
||||
|
||||
- 创建一个专用的本地用户来运行 Headscale
|
||||
- 提供默认的配置文件
|
||||
- 将 Headscale 安装为系统服务
|
||||
|
||||
!!! 警告 "社区包可能已过时"
|
||||
|
||||
本页提到的包可能已经过时或不再维护。建议使用 [官方版本](./official.md) 来获取最新的稳定版本或测试预发布版本。
|
||||
|
||||
[](https://repology.org/project/headscale/versions)
|
||||
|
||||
## Arch Linux
|
||||
|
||||
Arch Linux 提供了 Headscale 的安装包，可以通过以下命令安装：
|
||||
|
||||
```shell
|
||||
pacman -S headscale
|
||||
```
|
||||
|
||||
如果你想安装最新的开发版本，可以使用 [AUR 包 `headscale-git`](https://aur.archlinux.org/packages/headscale-git)。
|
||||
|
||||
## Fedora, RHEL, CentOS
|
||||
|
||||
针对基于 RPM 的发行版，可以在以下地址找到第三方仓库：
|
||||
<https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/>
|
||||
该网站提供了详细的设置和安装说明。
|
||||
|
||||
## Nix, NixOS
|
||||
|
||||
Nix 提供了一个名为 `headscale` 的包。安装细节可以参考 [NixOS 包页面](https://search.nixos.org/packages?show=headscale)。
|
||||
|
||||
## Gentoo
|
||||
|
||||
可以通过以下命令安装 Headscale：
|
||||
|
||||
```shell
|
||||
emerge --ask net-vpn/headscale
|
||||
```
|
||||
|
||||
Gentoo 的具体文档可以在 [这里](https://wiki.gentoo.org/wiki/User:Maffblaster/Drafts/Headscale) 找到。
|
||||
|
||||
## OpenBSD
|
||||
|
||||
Headscale 已经包含在 OpenBSD 的 ports 中。安装时会通过 `rc.d` 将 Headscale 设置为系统服务，并在安装完成后提供使用说明。
|
||||
|
||||
```shell
|
||||
pkg_add headscale
|
||||
```
|
||||
151
docs/zh/setup/install/container.md
Normal file
151
docs/zh/setup/install/container.md
Normal file
@ -0,0 +1,151 @@
|
||||
# 在容器中运行 Headscale
|
||||
|
||||
!!! 警告 "社区文档"
|
||||
|
||||
本页面并非由 Headscale 官方维护，而是由社区成员编写。Headscale 开发者**未验证**其内容。
|
||||
|
||||
**内容可能已过时或缺少必要步骤**。
|
||||
|
||||
本文档旨在指导用户如何在容器中设置和运行 Headscale。虽然以 [Docker](https://www.docker.com) 作为参考容器实现，但同样适用于其他容器工具，如 [Podman](https://podman.io)。Headscale 的 Docker 镜像可以在 Docker Hub 上找到：[这里](https://hub.docker.com/r/headscale/headscale)。
|
||||
|
||||
## 配置并运行 Headscale
|
||||
|
||||
1. **准备主机目录**
|
||||
在 Docker 主机上选择一个目录，用于存放 Headscale 的配置文件和 [SQLite](https://www.sqlite.org/) 数据库：
|
||||
|
||||
```shell
|
||||
mkdir -p ./headscale/config
|
||||
cd ./headscale
|
||||
```
|
||||
|
||||
2. **下载并调整配置文件**
|
||||
下载适合你版本的示例配置文件，并保存为 `/etc/headscale/config.yaml`。根据你的环境调整配置。详情请参考 [配置文档](../../../en/ref/configuration.md)。
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /etc/headscale
|
||||
sudo nano /etc/headscale/config.yaml
|
||||
```
|
||||
|
||||
或者，你可以通过添加 `--volume $(pwd)/lib:/var/lib/headscale` 和 `--volume $(pwd)/run:/var/run/headscale` 来挂载主机的 `/var/lib` 和 `/var/run` 目录。
|
||||
|
||||
3. **启动 Headscale 服务**
|
||||
在主机 Headscale 目录下运行以下命令：
|
||||
|
||||
```shell
|
||||
docker run \
|
||||
--name headscale \
|
||||
--detach \
|
||||
--volume $(pwd)/config:/etc/headscale/ \
|
||||
--publish 127.0.0.1:8080:8080 \
|
||||
--publish 127.0.0.1:9090:9090 \
|
||||
headscale/headscale:<VERSION> \
|
||||
serve
|
||||
```
|
||||
|
||||
注意：如果你希望外部访问容器，可以将 `127.0.0.1:8080:8080` 改为 `0.0.0.0:8080:8080`。
|
||||
|
||||
此命令会将 `config/` 挂载到 `/etc/headscale`，将容器的 8080 端口映射到主机，使 Headscale 服务可用，并在后台运行。
|
||||
|
||||
**示例 `docker-compose.yaml` 文件**：
|
||||
|
||||
```yaml
|
||||
version: "3.7"
|
||||
|
||||
services:
|
||||
headscale:
|
||||
image: headscale/headscale:<VERSION>
|
||||
restart: unless-stopped
|
||||
container_name: headscale
|
||||
ports:
|
||||
- "127.0.0.1:8080:8080"
|
||||
- "127.0.0.1:9090:9090"
|
||||
volumes:
|
||||
# 请将 <CONFIG_PATH> 替换为你刚创建的配置文件夹的完整路径
|
||||
- <CONFIG_PATH>:/etc/headscale
|
||||
command: serve
|
||||
```
|
||||
|
||||
4. **验证 Headscale 是否正常运行**
|
||||
查看容器日志：
|
||||
|
||||
```shell
|
||||
docker logs --follow headscale
|
||||
```
|
||||
|
||||
查看正在运行的容器：
|
||||
|
||||
```shell
|
||||
docker ps
|
||||
```
|
||||
|
||||
验证 Headscale 是否可用：
|
||||
|
||||
```shell
|
||||
curl http://127.0.0.1:9090/metrics
|
||||
```
|
||||
|
||||
5. **创建 Headscale 用户**
|
||||
在容器中执行以下命令创建用户：
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale users create myfirstuser
|
||||
```
|
||||
|
||||
### 注册设备（普通登录）
|
||||
|
||||
在客户端设备上执行以下命令：
|
||||
|
||||
```shell
|
||||
tailscale up --login-server YOUR_HEADSCALE_URL
|
||||
```
|
||||
|
||||
如果 Headscale 运行在容器中，可以通过以下命令注册设备：
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
|
||||
```
|
||||
|
||||
### 使用预认证密钥注册设备
|
||||
|
||||
生成预认证密钥：
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
||||
```
|
||||
|
||||
这将返回一个预认证密钥，可以在 `tailscale` 命令中使用：
|
||||
|
||||
```shell
|
||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
||||
```
|
||||
|
||||
## 调试运行在 Docker 中的 Headscale
|
||||
|
||||
`headscale/headscale` Docker 容器基于“无发行版”镜像，不包含 shell 或其他调试工具。如果需要调试，可以使用 `-debug` 变体，例如 `headscale/headscale:x.x.x-debug`。
|
||||
|
||||
### 运行调试容器
|
||||
|
||||
使用与普通容器相同的命令，但将 `headscale/headscale:x.x.x` 替换为 `headscale/headscale:x.x.x-debug`（`x.x.x` 是 Headscale 版本）。两个容器兼容，可以交替使用。
|
||||
|
||||
### 在调试容器中执行命令
|
||||
|
||||
调试容器的默认命令是运行 Headscale，路径为 `/ko-app/headscale`。
|
||||
|
||||
此外，调试容器包含一个极简的 Busybox shell。
|
||||
|
||||
启动容器的 shell：
|
||||
|
||||
```shell
|
||||
docker run -it headscale/headscale:x.x.x-debug sh
|
||||
```
|
||||
|
||||
也可以直接执行命令，例如列出 `/ko-app` 目录：
|
||||
|
||||
```shell
|
||||
docker run headscale/headscale:x.x.x-debug ls /ko-app
|
||||
```
|
||||
|
||||
使用 `docker exec -it` 可以在现有容器中运行命令。
|
||||
113
docs/zh/setup/install/official.md
Normal file
113
docs/zh/setup/install/official.md
Normal file
@ -0,0 +1,113 @@
|
||||
以下是您提供的英文内容翻译为中文：
|
||||
|
||||
---
|
||||
|
||||
# 官方版本
|
||||
|
||||
Headscale 的官方版本提供多种平台的二进制文件以及适用于 Debian 和 Ubuntu 的 DEB 包。两者均可在 [GitHub 发布页面](https://github.com/juanfont/headscale/releases) 获取。
|
||||
|
||||
## 使用 Debian/Ubuntu 软件包（推荐）
|
||||
|
||||
推荐在基于 Debian 的系统上使用我们的 DEB 包来安装 Headscale，因为这些软件包会配置一个本地用户来运行 Headscale，提供默认配置文件，并附带 systemd 服务文件。支持的发行版包括 Ubuntu 20.04 或更新版本，以及 Debian 11 或更新版本。
|
||||
|
||||
1. 下载适用于您平台的最新 [Headscale 软件包](https://github.com/juanfont/headscale/releases/latest)（Ubuntu 和 Debian 使用 `.deb` 文件）。
|
||||
|
||||
```shell
|
||||
HEADSCALE_VERSION="" # 参见上方链接获取最新版本号，例如 "X.Y.Z"（注意：不要添加 "v" 前缀！）
|
||||
HEADSCALE_ARCH="" # 您的系统架构，例如 "amd64"
|
||||
wget --output-document=headscale.deb \
|
||||
"https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
|
||||
```
|
||||
|
||||
2. 安装 Headscale：
|
||||
|
||||
```shell
|
||||
sudo apt install ./headscale.deb
|
||||
```
|
||||
|
||||
3. [编辑配置文件以配置 Headscale](../../../en/ref/configuration.md)：
|
||||
|
||||
```shell
|
||||
sudo nano /etc/headscale/config.yaml
|
||||
```
|
||||
|
||||
4. 启用并启动 Headscale 服务：
|
||||
|
||||
```shell
|
||||
sudo systemctl enable --now headscale
|
||||
```
|
||||
|
||||
5. 验证 Headscale 是否正常运行：
|
||||
|
||||
```shell
|
||||
sudo systemctl status headscale
|
||||
```
|
||||
|
||||
## 使用独立二进制文件（高级）
|
||||
|
||||
!!! warning "高级"
|
||||
|
||||
此安装方法被认为是高级的，因为用户需要自行管理本地用户和 systemd 服务。如果可能，请使用 [DEB 软件包](#使用-debianubuntu-软件包推荐) 或 [社区包](community.md)。
|
||||
|
||||
本节介绍根据 [要求和假设](../requirements.md#假设) 安装 Headscale 的步骤。Headscale 由专用本地用户运行，服务本身由 systemd 管理。
|
||||
|
||||
1. 从 [GitHub 发布页面](https://github.com/juanfont/headscale/releases) 下载最新的 `headscale` 二进制文件：
|
||||
|
||||
```shell
|
||||
sudo wget --output-document=/usr/local/bin/headscale \
|
||||
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE 版本>/headscale_<HEADSCALE 版本>_linux_<架构>
|
||||
```
|
||||
|
||||
2. 使 `headscale` 可执行：
|
||||
|
||||
```shell
|
||||
sudo chmod +x /usr/local/bin/headscale
|
||||
```
|
||||
|
||||
3. 添加一个专用的本地用户来运行 Headscale：
|
||||
|
||||
```shell
|
||||
sudo useradd \
|
||||
--create-home \
|
||||
--home-dir /var/lib/headscale/ \
|
||||
--system \
|
||||
--user-group \
|
||||
--shell /usr/sbin/nologin \
|
||||
headscale
|
||||
```
|
||||
|
||||
4. 下载所需版本的示例配置文件并保存为 `/etc/headscale/config.yaml`。根据本地环境调整配置。详情请参见 [配置文件](../../../en/ref/configuration.md)。
|
||||
|
||||
```shell
|
||||
sudo mkdir -p /etc/headscale
|
||||
sudo nano /etc/headscale/config.yaml
|
||||
```
|
||||
|
||||
5. 将 [Headscale 的 systemd 服务文件](../../../en/packaging/headscale.systemd.service) 复制到 `/etc/systemd/system/headscale.service` 并根据本地设置进行调整。以下参数可能需要修改： `ExecStart`、`WorkingDirectory`、`ReadWritePaths`。
|
||||
|
||||
6. 在 `/etc/headscale/config.yaml` 中，将默认的 `headscale` Unix 套接字路径替换为可由 `headscale` 用户或组写入的路径：
|
||||
|
||||
```yaml title="config.yaml"
|
||||
unix_socket: /var/run/headscale/headscale.sock
|
||||
```
|
||||
|
||||
7. 重新加载 systemd 以加载新配置文件：
|
||||
|
||||
```shell
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
8. 启用并启动新的 Headscale 服务：
|
||||
|
||||
```shell
|
||||
systemctl enable --now headscale
|
||||
```
|
||||
|
||||
9. 验证 Headscale 是否正常运行：
|
||||
|
||||
```shell
|
||||
systemctl status headscale
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
64
docs/zh/setup/install/source.md
Normal file
64
docs/zh/setup/install/source.md
Normal file
@ -0,0 +1,64 @@
|
||||
# 从源码构建
|
||||
|
||||
!!! 警告 "社区文档"
|
||||
|
||||
本页面并非由 Headscale 官方维护，而是由社区成员编写。Headscale 开发者**未验证**其内容。
|
||||
|
||||
**内容可能已过时或缺少必要步骤**。
|
||||
|
||||
Headscale 可以通过最新版本的 [Go](https://golang.org) 和 [Buf](https://buf.build)（Protobuf 生成器）从源码构建。更多信息请参考 [GitHub README 中的贡献部分](https://github.com/juanfont/headscale#contributing)。
|
||||
|
||||
## OpenBSD
|
||||
|
||||
### 从源码安装
|
||||
|
||||
```shell
|
||||
# 安装依赖
|
||||
pkg_add go
|
||||
|
||||
# 克隆 Headscale 仓库
|
||||
git clone https://github.com/juanfont/headscale.git
|
||||
|
||||
cd headscale
|
||||
|
||||
# 可选：切换到某个发布版本
|
||||
# 选项 a. 你可以在 https://github.com/juanfont/headscale/releases/latest 找到官方发布版本
|
||||
# 选项 b. 获取最新的标签，可能是测试版
|
||||
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
||||
|
||||
git checkout $latestTag
|
||||
|
||||
# 构建 Headscale
|
||||
go build -ldflags="-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=$latestTag" -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash=HASH" github.com/juanfont/headscale
|
||||
|
||||
# 赋予可执行权限
|
||||
chmod a+x headscale
|
||||
|
||||
# 复制到 /usr/local/sbin
|
||||
cp headscale /usr/local/sbin
|
||||
```
|
||||
|
||||
### 通过交叉编译从源码安装
|
||||
|
||||
```shell
|
||||
# 安装依赖
|
||||
# 1. go v1.20+：Headscale 0.21 以上版本需要 Go 1.20+ 才能编译
|
||||
# 2. gmake：Headscale 仓库中的 Makefile 使用 GNU make 语法
|
||||
|
||||
# 克隆 Headscale 仓库
|
||||
git clone https://github.com/juanfont/headscale.git
|
||||
|
||||
cd headscale
|
||||
|
||||
# 可选：切换到某个发布版本
|
||||
# 选项 a. 你可以在 https://github.com/juanfont/headscale/releases/latest 找到官方发布版本
|
||||
# 选项 b. 获取最新的标签，可能是测试版
|
||||
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
||||
|
||||
git checkout $latestTag
|
||||
|
||||
# 交叉编译
|
||||
make build GOOS=openbsd
|
||||
|
||||
# 将编译好的 headscale 复制到 OpenBSD 机器，并放到 /usr/local/sbin
|
||||
```
|
||||
28
docs/zh/setup/requirements.md
Normal file
28
docs/zh/setup/requirements.md
Normal file
@ -0,0 +1,28 @@
|
||||
# Requirements
|
||||
|
||||
Headscale should just work as long as the following requirements are met:
|
||||
|
||||
- A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is
|
||||
recommended.
|
||||
- Headscale is served via HTTPS on port 443[^1].
|
||||
- A reasonably modern Linux or BSD based operating system.
|
||||
- A dedicated local user account to run headscale.
|
||||
- A little bit of command line knowledge to configure and operate headscale.
|
||||
|
||||
## Assumptions
|
||||
|
||||
The headscale documentation and the provided examples are written with a few assumptions in mind:
|
||||
|
||||
- Headscale is running as system service via a dedicated local user `headscale`.
|
||||
- The [configuration](../../en/ref/configuration.md) is loaded from `/etc/headscale/config.yaml`.
|
||||
- SQLite is used as database.
|
||||
- The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in `/var/lib/headscale`.
|
||||
- URLs and values that need to be replaced by the user are either denoted as `<VALUE_TO_CHANGE>` or use placeholder
|
||||
values such as `headscale.example.com`.
|
||||
|
||||
Please adjust to your local environment accordingly.
|
||||
|
||||
[^1]:
|
||||
The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS
|
||||
on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production
|
||||
setups. See [issue 2164](https://github.com/juanfont/headscale/issues/2164) for more information.
|
||||
9
docs/zh/setup/upgrade.md
Normal file
9
docs/zh/setup/upgrade.md
Normal file
@ -0,0 +1,9 @@
|
||||
# 升级现有安装
|
||||
|
||||
将现有的 Headscale 安装更新到新版本：
|
||||
|
||||
- 阅读 [GitHub 发布页面](https://github.com/juanfont/headscale/releases) 上的新版本公告。该公告列出了发布的变更及可能的破坏性变更。
|
||||
- **创建数据库备份。**
|
||||
- 将 Headscale 更新到新版本，最好按照相同的安装方法进行。
|
||||
- 比较并更新 [配置文件](../ref/configuration.md)。
|
||||
- 重新启动 Headscale。
|
||||
15
docs/zh/usage/connect/android.md
Normal file
15
docs/zh/usage/connect/android.md
Normal file
@ -0,0 +1,15 @@
|
||||
# 连接 Android 客户端
|
||||
|
||||
本文档旨在说明用户如何将官方 Android [Tailscale](https://tailscale.com) 客户端与 Headscale 结合使用。
|
||||
|
||||
## 安装
|
||||
|
||||
从 [Google Play Store](https://play.google.com/store/apps/details?id=com.tailscale.ipn) 或 [F-Droid](https://f-droid.org/packages/com.tailscale.ipn/) 安装官方 Tailscale Android 客户端。
|
||||
|
||||
## 配置 Headscale URL
|
||||
|
||||
- 打开应用，然后选择右上角的设置菜单。
|
||||
- 点击 “账户 (Accounts)”。
|
||||
- 在右上角的 kebab 菜单图标（三个点）中，选择 “使用备用服务器 (Use an alternate server)”。
|
||||
- 输入你的服务器 URL（例如 `https://headscale.example.com`），然后按照说明操作。
|
||||
|
||||
65
docs/zh/usage/connect/apple.md
Normal file
65
docs/zh/usage/connect/apple.md
Normal file
@ -0,0 +1,65 @@
|
||||
# 连接 Apple 客户端
|
||||
|
||||
本文档旨在说明用户如何将官方 iOS 和 macOS [Tailscale](https://tailscale.com) 客户端与 Headscale 结合使用。
|
||||
|
||||
!!! info "Headscale 实例上的说明"
|
||||
|
||||
关于如何连接你的 Apple 设备的信息终结点也可以在你的运行实例上的 `/apple` 处获得。
|
||||
|
||||
## iOS
|
||||
|
||||
### 安装
|
||||
|
||||
从 [App Store](https://apps.apple.com/app/tailscale/id1470499037) 安装官方 Tailscale iOS 客户端。
|
||||
|
||||
### 配置 Headscale URL
|
||||
|
||||
- 打开 Tailscale 应用
|
||||
- 点击右上角的帐户图标，然后选择 “登录… (Log in…)”。
|
||||
- 点击右上角的选项菜单按钮，然后选择 “使用自定义协调服务器 (Use custom coordination server)”。
|
||||
- 输入你的实例 URL（例如 `https://headscale.example.com`）。
|
||||
- 输入你的凭据并登录。 Headscale 现在应该可以在你的 iOS 设备上使用了。
|
||||
|
||||
## macOS
|
||||
|
||||
### 安装
|
||||
|
||||
选择一个可用的 [macOS Tailscale 客户端](https://tailscale.com/kb/1065/macos-variants) 并安装它。
|
||||
|
||||
### 配置 Headscale URL
|
||||
|
||||
#### 命令行
|
||||
|
||||
使用 Tailscale 的登录命令连接到你的 Headscale 实例（例如 `https://headscale.example.com`）：
|
||||
|
||||
```
|
||||
tailscale login --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
#### GUI
|
||||
|
||||
- Option + 单击菜单中的 Tailscale 图标，并将鼠标悬停在 “调试 (Debug)” 菜单上。
|
||||
- 在 “自定义登录服务器 (Custom Login Server)” 下，选择 “添加帐户… (Add Account…)”。
|
||||
- 输入你的 Headscale 实例的 URL（例如 `https://headscale.example.com`），然后按 “添加帐户 (Add Account)”。
|
||||
- 按照浏览器中的登录步骤操作。
|
||||
|
||||
## tvOS
|
||||
|
||||
### 安装
|
||||
|
||||
从 [App Store](https://apps.apple.com/app/tailscale/id1470499037) 安装官方 Tailscale tvOS 客户端。
|
||||
|
||||
!!! danger
|
||||
|
||||
**安装后不要打开 Tailscale 应用！**
|
||||
|
||||
### 配置 Headscale URL
|
||||
|
||||
- 打开 “设置 (Settings)”（Apple tvOS 设置）> “应用 (Apps)” > “Tailscale”。
|
||||
- 在 “备用协调服务器 URL (ALTERNATE COORDINATION SERVER URL)” 下，选择 “URL”。
|
||||
- 输入你的 Headscale 实例的 URL（例如 `https://headscale.example.com`），然后按 “确定 (OK)”。
|
||||
- 返回 tvOS 主屏幕。
|
||||
- 打开 Tailscale。
|
||||
- 点击 “安装 VPN 配置 (Install VPN configuration)” 按钮，然后点击 “允许 (Allow)” 按钮确认出现的弹出窗口。
|
||||
- 扫描二维码，然后按照登录步骤操作。
|
||||
|
||||
57
docs/zh/usage/connect/windows.md
Normal file
57
docs/zh/usage/connect/windows.md
Normal file
@ -0,0 +1,57 @@
|
||||
# 连接 Windows 客户端
|
||||
|
||||
本文档旨在说明用户如何将官方 Windows [Tailscale](https://tailscale.com) 客户端与 Headscale 结合使用。
|
||||
|
||||
!!! info "Headscale 实例上的说明"
|
||||
|
||||
关于如何连接你的 Windows 设备的信息终结点也可以在你的运行实例上的 `/windows` 处获得。
|
||||
|
||||
## 安装
|
||||
|
||||
下载 [官方 Windows 客户端](https://tailscale.com/download/windows) 并安装它。
|
||||
|
||||
## 配置 Headscale URL
|
||||
|
||||
打开命令提示符或 Powershell，并使用 Tailscale 的登录命令连接到你的 Headscale 实例（例如 `https://headscale.example.com`）：
|
||||
|
||||
```
|
||||
tailscale login --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
按照打开的浏览器窗口中的说明完成配置。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 无人值守模式
|
||||
|
||||
默认情况下，Tailscale 的 Windows 客户端仅在用户登录时运行。 如果你希望 Tailscale 始终运行，请启用 “无人值守模式 (Unattended mode)”:
|
||||
|
||||
- 单击 Tailscale 托盘图标，然后选择 “首选项 (Preferences)”。
|
||||
- 启用 “无人值守运行 (Run unattended)”。
|
||||
- 确认 “无人值守模式 (Unattended mode)” 消息。
|
||||
|
||||
另请参阅 [当我不登录到我的计算机时，保持 Tailscale 运行](https://tailscale.com/kb/1088/run-unattended)。
|
||||
|
||||
### 节点注册失败
|
||||
|
||||
如果你在 Headscale 输出中看到重复的消息，例如：
|
||||
|
||||
```
|
||||
[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
||||
```
|
||||
|
||||
打开 `DEBUG` 日志记录并查找：
|
||||
|
||||
```
|
||||
2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
|
||||
```
|
||||
|
||||
这通常意味着上面的注册表项未正确设置。
|
||||
|
||||
要重置并重试，请务必执行以下操作：
|
||||
|
||||
1. 关闭 Tailscale 服务（或在托盘中运行的客户端）。
|
||||
2. 删除 Tailscale 应用程序数据文件夹，该文件夹位于 `C:\Users\<USERNAME>\AppData\Local\Tailscale`，然后尝试重新连接。
|
||||
3. 确保 Windows 节点已从 Headscale 中删除（以确保全新设置）。
|
||||
4. 在 Windows 计算机上启动 Tailscale 并重试登录。
|
||||
|
||||
121
docs/zh/usage/getting-started.md
Normal file
121
docs/zh/usage/getting-started.md
Normal file
@ -0,0 +1,121 @@
|
||||
# 入门指南
|
||||
|
||||
本页面将帮助你开始使用 Headscale，并提供一些 `headscale` 命令行工具的使用示例。
|
||||
|
||||
!!! note "前置条件"
|
||||
|
||||
* Headscale 已安装并作为系统服务运行。请阅读 [设置部分](../setup/requirements.md) 获取安装说明。
|
||||
* 配置文件已存在并已根据你的环境进行调整，详细信息请参阅 [配置](../ref/configuration.md)。
|
||||
* Headscale 可以从互联网访问。 通过在浏览器中打开特定于客户端的设置说明来验证这一点，例如 [headscale.example.com](https://headscale.example.com)/windows
|
||||
* 已安装 Tailscale 客户端，更多信息请参阅 [客户端和操作系统支持](../about/clients.md)。
|
||||
|
||||
## 获取帮助
|
||||
|
||||
`headscale` 命令行工具提供了内置帮助。 要显示可用命令及其参数和选项，请运行：
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
# 显示帮助
|
||||
headscale help
|
||||
|
||||
# 显示特定命令的帮助
|
||||
headscale <COMMAND> --help
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
# 显示帮助
|
||||
docker exec -it headscale \
|
||||
headscale help
|
||||
|
||||
# 显示特定命令的帮助
|
||||
docker exec -it headscale \
|
||||
headscale <COMMAND> --help
|
||||
```
|
||||
|
||||
## 管理 Headscale 用户
|
||||
|
||||
在 Headscale 中，节点（也称为机器或设备）始终分配给 Headscale 用户。 这样的 Headscale 用户可以拥有分配给他们的多个节点，并且可以使用 `headscale users` 命令进行管理。 调用内置帮助以获取更多信息：`headscale users --help`。
|
||||
|
||||
### 创建 Headscale 用户
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale users create <USER>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale users create <USER>
|
||||
```
|
||||
|
||||
### 列出现有的 Headscale 用户
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale users list
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale users list
|
||||
```
|
||||
|
||||
## 注册节点
|
||||
|
||||
必须先注册节点，才能使用 Headscale 与 Tailscale 进行协调。 以下示例适用于 Linux/BSD 操作系统上的 Tailscale 客户端。 或者，按照说明连接 [Android](connect/android.md)、[Apple](connect/apple.md) 或 [Windows](connect/windows.md) 设备。
|
||||
|
||||
### 常规交互式登录
|
||||
|
||||
在客户端机器上，运行 `tailscale up` 命令，并将你的 Headscale 实例的 FQDN 作为参数提供：
|
||||
|
||||
```shell
|
||||
tailscale up --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
通常，会打开一个包含进一步说明的浏览器窗口，其中包含 `<YOUR_MACHINE_KEY>` 的值。 在你的 Headscale 服务器上批准并注册该节点：
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||
```
|
||||
|
||||
### 使用预授权密钥
|
||||
|
||||
也可以生成预授权密钥并以非交互方式注册节点。 首先，在 Headscale 实例上生成预授权密钥。 默认情况下，该密钥有效期为一个小时，并且只能使用一次（有关其他选项，请参阅 `headscale preauthkeys --help`）：
|
||||
|
||||
=== "Native"
|
||||
|
||||
```shell
|
||||
headscale preauthkeys create --user <USER>
|
||||
```
|
||||
|
||||
=== "Container"
|
||||
|
||||
```shell
|
||||
docker exec -it headscale \
|
||||
headscale preauthkeys create --user <USER>
|
||||
```
|
||||
|
||||
该命令成功后会返回预授权密钥，该密钥用于通过 `tailscale up` 命令将节点连接到 Headscale 实例：
|
||||
|
||||
```shell
|
||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
||||
```
|
||||
|
||||
89
mkdocs.yml
89
mkdocs.yml
@ -1,19 +1,15 @@
|
||||
---
|
||||
site_name: Headscale
|
||||
site_url: https://juanfont.github.io/headscale/
|
||||
edit_uri: blob/main/docs/ # Change the master branch to main as we are using main as a main branch
|
||||
edit_uri: blob/main/docs/
|
||||
site_author: Headscale authors
|
||||
site_description: >-
|
||||
An open source, self-hosted implementation of the Tailscale control server.
|
||||
|
||||
# Repository
|
||||
repo_name: juanfont/headscale
|
||||
repo_url: https://github.com/juanfont/headscale
|
||||
|
||||
# Copyright
|
||||
copyright: Copyright © 2025 Headscale authors
|
||||
|
||||
# Configuration
|
||||
theme:
|
||||
name: material
|
||||
features:
|
||||
@ -22,24 +18,17 @@ theme:
|
||||
- content.action.view
|
||||
- content.code.annotate
|
||||
- content.code.copy
|
||||
# - content.tabs.link
|
||||
- content.tooltips
|
||||
# - header.autohide
|
||||
# - navigation.expand
|
||||
- navigation.footer
|
||||
- navigation.indexes
|
||||
# - navigation.instant
|
||||
# - navigation.prune
|
||||
- navigation.sections
|
||||
- navigation.tabs
|
||||
# - navigation.tabs.sticky
|
||||
- navigation.top
|
||||
- navigation.tracking
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
- toc.follow
|
||||
# - toc.integrate
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: white
|
||||
@ -56,17 +45,15 @@ theme:
|
||||
favicon: assets/favicon.png
|
||||
logo: ./logo/headscale3-dots.svg
|
||||
|
||||
# Excludes
|
||||
exclude_docs: |
|
||||
/packaging/README.md
|
||||
/packaging/postinstall.sh
|
||||
/packaging/postremove.sh
|
||||
/requirements.txt
|
||||
|
||||
# Plugins
|
||||
plugins:
|
||||
- search:
|
||||
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
||||
separator: '[\s\-,:!=$$()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
||||
- macros:
|
||||
- include-markdown:
|
||||
- minify:
|
||||
@ -88,8 +75,17 @@ plugins:
|
||||
tls.md: ref/tls.md
|
||||
web-ui.md: ref/integration/web-ui.md
|
||||
windows-client.md: usage/connect/windows.md
|
||||
- i18n:
|
||||
docs_structure: folder
|
||||
languages:
|
||||
- locale: en
|
||||
default: true
|
||||
name: English
|
||||
build: true
|
||||
- locale: zh
|
||||
name: Chinese
|
||||
build: true
|
||||
|
||||
# Customization
|
||||
extra:
|
||||
version:
|
||||
alias: true
|
||||
@ -108,7 +104,6 @@ extra:
|
||||
headscale:
|
||||
version: 0.25.0
|
||||
|
||||
# Extensions
|
||||
markdown_extensions:
|
||||
- abbr
|
||||
- admonition
|
||||
@ -150,41 +145,39 @@ markdown_extensions:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
|
||||
# Page tree
|
||||
nav:
|
||||
- Welcome: index.md
|
||||
- About:
|
||||
- FAQ: about/faq.md
|
||||
- Features: about/features.md
|
||||
- Clients: about/clients.md
|
||||
- Getting help: about/help.md
|
||||
- Releases: about/releases.md
|
||||
- Contributing: about/contributing.md
|
||||
- Sponsor: about/sponsor.md
|
||||
|
||||
- FAQ: about/faq.md
|
||||
- Features: about/features.md
|
||||
- Clients: about/clients.md
|
||||
- Getting help: about/help.md
|
||||
- Releases: about/releases.md
|
||||
- Contributing: about/contributing.md
|
||||
- Sponsor: about/sponsor.md
|
||||
- Setup:
|
||||
- Requirements and Assumptions: setup/requirements.md
|
||||
- Installation:
|
||||
- Official releases: setup/install/official.md
|
||||
- Community packages: setup/install/community.md
|
||||
- Container: setup/install/container.md
|
||||
- Build from source: setup/install/source.md
|
||||
- Requirements and Assumptions: setup/requirements.md
|
||||
- Installation:
|
||||
- Official releases: setup/install/official.md
|
||||
- Community packages: setup/install/community.md
|
||||
- Container: setup/install/container.md
|
||||
- Build from source: setup/install/source.md
|
||||
- Upgrade: setup/upgrade.md
|
||||
- Usage:
|
||||
- Getting started: usage/getting-started.md
|
||||
- Connect a node:
|
||||
- Android: usage/connect/android.md
|
||||
- Apple: usage/connect/apple.md
|
||||
- Windows: usage/connect/windows.md
|
||||
- Getting started: usage/getting-started.md
|
||||
- Connect a node:
|
||||
- Android: usage/connect/android.md
|
||||
- Apple: usage/connect/apple.md
|
||||
- Windows: usage/connect/windows.md
|
||||
- Reference:
|
||||
- Configuration: ref/configuration.md
|
||||
- OIDC authentication: ref/oidc.md
|
||||
- Exit node: ref/exit-node.md
|
||||
- TLS: ref/tls.md
|
||||
- ACLs: ref/acls.md
|
||||
- DNS: ref/dns.md
|
||||
- Remote CLI: ref/remote-cli.md
|
||||
- Integration:
|
||||
- Reverse proxy: ref/integration/reverse-proxy.md
|
||||
- Web UI: ref/integration/web-ui.md
|
||||
- Tools: ref/integration/tools.md
|
||||
- Configuration: ref/configuration.md
|
||||
- OIDC authentication: ref/oidc.md
|
||||
- Exit node: ref/exit-node.md
|
||||
- TLS: ref/tls.md
|
||||
- ACLs: ref/acls.md
|
||||
- DNS: ref/dns.md
|
||||
- Remote CLI: ref/remote-cli.md
|
||||
- Integration:
|
||||
- Reverse proxy: ref/integration/reverse-proxy.md
|
||||
- Web UI: ref/integration/web-ui.md
|
||||
- Tools: ref/integration/tools.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user