🏠 localias

Localias 是一个供开发者安全管理本地开发服务器别名的工具。

使用 Localias 可以在浏览器和命令行中将 https://server.test 重定向到 http://localhost:3000。

主要特性

在 URL 中使用方便的名称，无需端口
在 TLS 后面提供开发网站，最大限度减少开发和生产环境之间的差异
- 不再有 CORS 问题！
- 可以设置安全 cookie！
适用于 MacOS、Linux，甚至 WSL2（！）
默认情况下，自动为所有别名配置并安装 TLS 证书
在添加和删除别名时自动更新 /etc/hosts，使其与所有工具兼容
可以选择在前台运行或作为后台守护进程运行
支持共享配置文件，让整个团队可以使用相同的开发服务别名
使用 caddy 代理请求和生成 TLS 证书，默认快速且安全
通过 mDNS 提供 .local 域名服务，让你可以从手机或连接到同一网络的任何其他设备访问开发服务器

安装

Homebrew:

# 安装
brew install peterldowns/tap/localias

Golang:

# 运行
go run github.com/peterldowns/localias/cmd/localias@latest --help
# 安装
go install github.com/peterldowns/localias/cmd/localias@latest

Nix (flakes):

# 运行
nix run github:peterldowns/localias -- --help
# 安装
nix profile install --refresh github:peterldowns/localias

手动下载二进制文件

访问最新的 Github 发布版本并选择适合的二进制文件。或者，点击以下快捷链接：

工作原理

Localias 包含两个部分：

配置文件
代理服务器

配置文件用于跟踪别名及其对应的本地端口。代理服务器则根据配置实际代理请求。

配置文件

每次运行 localias 时，它会按以下顺序查找配置文件，并使用找到的第一个：

如果你通过 --configfile <路径> 显式指定，它将尝试使用 <路径>
如果你设置了环境变量 LOCALIAS_CONFIGFILE=<路径>，它将尝试使用 <路径>
如果当前目录有 .localias.yaml，它将使用 $pwd/.localias.yaml
如果你在 git 仓库中，并且仓库根目录有 .localias.yaml，使用 $repo_root/.localias.yaml
否则，使用 $XDG_CONFIG_HOME/localias.yaml，如果不存在则创建
- 在 MacOS 上，默认为 ~/Library/Application\ Support/localias.yaml
- 在 Linux 或 WSL 上，默认为 ~/.config/localias.yaml

这意味着你的整个开发团队可以通过在 git 仓库根目录添加 .localias.yaml 来共享相同的别名。

要显示当前使用的配置文件，可以运行：

# 打印当前配置文件的路径
localias debug config
# 打印当前配置文件的内容
localias debug config --print

以下命令直接与配置文件交互：

# 添加或编辑别名
localias set <别名> <端口>
# 清除所有别名
localias clear
# 列出所有别名
localias list
# 删除别名
localias remove <别名>

配置文件只是一个 <别名>: <端口> 的 YAML 映射！例如，这是一个有效的配置文件：

bareTLD: 9003 # 通过 https 和 http 提供服务
implicitly_secure.test: 9002 # 通过 https 和 http 提供服务
https://explicit_secure.test: 9000 # 通过 https 和 http 提供服务
http://explicit_insecure.test: 9001 # 仅通过 http 提供服务

代理服务器

当你执行 localias run 或 localias start 来运行代理服务器时，Localias 执行以下操作：

读取当前 Localias 配置文件，找到所有当前别名及其指向的端口
检查 /etc/hosts 文件，确保每个别名都存在
- 添加任何尚未存在的新别名
- 删除不再在 Localias 配置中的旧别名
- 仅在有更改时更新文件，因为这需要 sudo 权限
运行 Caddy 代理服务器
- 如果 Caddy 尚未生成本地根证书：
  - 生成本地根证书以签署 TLS 证书
  - 将本地根证书安装到系统的信任存储，如果存在并可访问 Firefox 证书存储，也安装到其中
- 生成 Caddy 配置，告诉它如何将每个别名重定向到正确的本地端口
- 为当前使用的每个别名生成并签署 TLS 证书
- 绑定到 80/443 端口以代理请求

Localias 需要提升权限才能执行这些作为代理服务器运行的一部分的操作：

编辑 /etc/hosts
将本地生成的根证书安装到系统存储
绑定到 80/443 端口以运行代理服务器

运行 Localias 时，每当需要执行这些操作，它都会使用 sudo 打开一个子 shell 来执行这些操作，这将提示你输入密码。Localias 不会读取或与你的密码交互。

Localias 完全是本地的，不执行任何遥测。

快速入门

首次运行服务器

安装 localias 后，你需要配置一些别名。在这个快速入门示例中，我们假设你在 http://localhost:3000 上运行本地 http 前端开发服务器，并希望能够在浏览器和像 curl 这样的工具中通过 https://frontend.test 访问它。

首先，创建别名：

$ localias set frontend.test 3000
[added] frontend.test -> 3000

你可以检查是否正确添加：

$ localias list
frontend.test -> 3000

配置就这么简单！

现在，启动代理服务器。你可以使用 localias run 在前台运行（使用 ctrl-c 停止），也可以使用 localias start 在后台启动服务器。在这个快速入门中，我们将在前台运行。

$ localias run
# 一些以 root 身份验证的提示
# ... 大量服务器日志，如下所示：
2023/05/02 23:12:58.218 INFO    tls.obtain      acquiring lock  {"identifier": "frontend.test"}
2023/05/02 23:12:58.229 INFO    tls.obtain      lock acquired   {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      obtaining certificate   {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      certificate obtained successfully       {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      releasing lock  {"identifier": "frontend.test"}
# 进程现在等待请求

这将至少提示你进行一次身份验证。每次 Localias 运行时，它都会：

自动编辑你的 /etc/hosts 文件，为每个别名添加条目
为你的别名签署 TLS 证书，如果尚未生成，则生成并安装自定义根证书到你的系统

这些步骤都需要 sudo 访问权限。但是启动/停止 Localias 只会在需要时提示 sudo，所以如果你按 control-C 并重新启动进程，就不会再次收到提示：

^C
$ localias run
# ... 大量服务器日志
# ... 但没有 sudo 提示！

恭喜，你已完成设置！在另一个控制台中启动你的开发服务器（或其中一个）。你应该能够在浏览器中访问 https://frontend.test，或使用 curl 发出请求，一切都能完美运行*。

* 你是否使用 Firefox，或者在 WSL 上？请参阅下面的注释，了解如何一次性安装 localias 根证书

作为守护进程运行

除了使用 localias run 将代理服务器作为前台进程显式运行外，你还可以使用 localias start 在后台运行 Localias。你可以使用以下命令与此守护进程交互：

# 将代理服务器作为守护进程启动
localias start
# 显示守护进程的状态
localias status
# 将最新配置应用于守护进程中的代理服务器
localias reload
# 停止守护进程
localias stop

作为守护进程运行时，如果你对配置进行任何更改，需要显式重新加载守护进程：

# 从 frontend.test -> 3000 开始
localias set frontend.test 3000
localias start
# 更新 frontend.test -> 4004
localias set frontend.test 4004
# 守护进程仍将使用 frontend.test -> 3000 运行，所以
# 要应用新更改，你需要重新加载它
localias reload

使用 CLI

localias 有许多不同的子命令，每个子命令都有文档（包括使用示例）。要查看可用的子命令，运行 localias。要查看任何命令的帮助，你可以运行 localias help $command 或 localias $command --help。

$ localias
安全管理本地开发服务器别名

用法：
  localias [标志]
  localias [命令]
示例：
  # 添加一个将 https://secure.test 转发到 http://127.0.0.1:9000 的别名
  localias set secure.test 9000
  # 更新现有别名以转发到不同端口
  localias set secure.test 9001
  # 删除一个别名
  localias rm secure.test
  # 列出所有别名
  localias list
  # 清除所有别名
  localias clear
  
  # 以守护进程方式启动代理服务器
  localias start
  # 显示守护进程状态
  localias status
  # 将最新配置应用到守护进程中的代理服务器
  localias reload
  # 停止守护进程
  localias stop
  # 在前台运行代理服务器
  localias run

可用命令：
  clear       清除所有别名
  help        获取任何命令的帮助
  list        列出所有别名
  reload      将最新配置应用到守护进程中的代理服务器
  rm          删除一个别名
  run         在前台运行代理服务器
  set         添加或编辑别名
  start       以守护进程方式启动代理服务器
  status      显示守护进程状态
  stop        停止守护进程
  version     显示此二进制文件的版本

标志：
  -c, --configfile string   要编辑的配置文件路径
  -h, --help                localias 的帮助
  -v, --version             localias 的版本

使用 "localias [命令] --help" 获取有关命令的更多信息。

# 勘误

## 为什么要构建这个？

Localias 是我一直想用于本地 Web 开发的工具。多年来一直只是访问 `localhost:8080`，我终于开始寻找解决方案，发现了 [hotel](https://github.com/typicode/hotel)（已停止维护）及其分支 [chalet](https://github.com/jeansaad/chalet)（仍在维护）。这些都是很棒的项目，为 Localias 提供了灵感，但我认为 Localias 的实现方式更好、更有用。

最后，[我的朋友 Justin 也想要这样的工具](https://twitter.com/jmduke/status/1628034461605539840?s=20)：

> 我发誓有一个工具可以让我这样做：
> 
> localhost:8000 → application.local  
> localhost:3000 → marketing.local  
> localhost:3002 → docs.local  
> 
> 但我怎么也想不起它的名字。有人知道我在说什么吗？

## 为什么不用 hotel/chalet？
Localias 旨在替代像 [hotel](https://github.com/typicode/hotel)/[chalet](https://github.com/jeansaad/chalet) 这样的替代工具。Hotel 已不再维护，Chalet 是 Hotel 的一个分支，基本上具有相同的功能。我认为 Localias 有以下优势：

  - Localias 是单一二进制文件。Hotel 需要有可用的 NodeJS 运行环境。
  - Localias 通过修改 `/etc/hosts`（以及 Windows 等效文件）来工作，这使得观察和调试变得容易。Hotel 要求你在浏览器或操作系统中将其配置为代理。
    - 使用 Localias 配置的别名也可以在命令行脚本或像 `curl` 这样的程序发送的请求中使用。Hotel 别名只在浏览器中有效。
  - Localias 允许你同时在不同的顶级域名上创建任意数量的别名。Hotel 只允许使用一个顶级域名。
  - Localias 会生成根证书和每个别名所需的任何证书，并将根证书安装在系统存储中，这样你就不会看到任何关于无效自签名证书的警告。Hotel 不进行任何 TLS 签名。
  - Localias 会自动发现提交到 git 仓库的配置文件，这使得与开发团队共享配置变得容易。Hotel 不允许共享配置文件。
  - Localias 不尝试进行任何类型的进程管理或启动，将这些完全留给你。Hotel 尝试为你运行和管理进程。

## 域名冲突和 HSTS

使用 Localias 时，你**不应该**创建与现有网站同名的别名。例如，如果你正在开发一个在生产环境中托管在 `https://example.com` 的网站，你真的不想为 `example.com` 创建一个指向你的开发服务器的本地别名。如果你这样做，你的浏览器可能会做一些你意想不到的事情：

- 你的开发 cookies 将被包含在对生产环境的请求中，反之亦然。如果你在打开/关闭 localias 并在开发和生产环境之间切换，这些 cookies 将相互冲突，通常会让你和你的网站变得非常困惑。
- 如果你的生产网站使用 [HSTS / 证书固定](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)，当你尝试将其用作开发服务器的本地别名时，你会看到非常可怕的错误。这是因为 localias 将使用不同的私钥提供内容，但 HSTS 明确告诉你的浏览器不允许这样做。

一般来说，最好完全避免这个问题，使用以 [`.test`](https://en.wikipedia.org/wiki/.test)、[`.example`](https://en.wikipedia.org/wiki/.example)、[`.localhost`](https://en.wikipedia.org/wiki/.localhost) 或其他未使用的顶级域名结尾的别名。

## `.local` 域名
由于 ["mDNS"，即"多播 DNS"](https://en.wikipedia.org/wiki/Multicast_DNS)，你创建的以 `.local` 结尾的任何别名都将被广播到你的整个网络。这使得从任何其他设备（包括你的手机）访问开发服务器变得容易，这让测试响应式网站变得非常简单。你只需创建一个以 `.local` 结尾的别名：

```console
$ localias add frontend.local 8080
[added] frontend.local -> 8080
$ localias add http://insecure.local 8080
[added] http://insecure.local 8080

当你从其他设备访问安全的本地别名时，你可能会收到证书警告提示。你可以放心地接受警告并继续访问该站点，这只是你的本地开发站点。

Localias 根证书和系统信任存储

Localias 的代理服务器 Caddy 会自动为你想要创建的任何安全别名生成证书。当 Localias 运行时，它会确保其根签名证书安装在 Mac 和 Linux 的系统存储中。如果你的浏览器从系统存储读取以确定信任哪些证书颁发机构，这意味着一切都会很好地为你开箱即用。

这意味着如果你在 MacOS/Linux 上使用 Safari/Edge/Chrome，你就可以直接使用，当你在浏览器中访问一个安全别名时，你会看到一个漂亮的"已验证"或"安全"状态。

WSL

当你在 WSL 内运行 Localias 时，基本上是在 Windows 主机上的 Linux 虚拟机内运行，Caddy 会生成证书并将它们安装到 Linux 虚拟机的信任存储中，但不会安装到父 Windows 主机。这意味着如果你使用在 Windows 中运行的浏览器，当你访问安全别名时，你会看到证书警告。

你可以通过明确地将 Localias 根证书安装到 Windows 机器的证书存储中来解决这个问题。你可以使用以下命令，它会提示你以管理员身份授权：

localias debug cert --install

Firefox

Firefox 默认不信任系统证书存储。这意味着不幸的是，如果你访问你的安全别名，你会看到一个警告，说证书无效。

在 MacOS/Linux 上，可以通过更改配置设置来配置 Firefox 信任系统存储。

打开 Firefox
访问 about:config

设置

security.enterprise_roots.enabled = true

退出并重新打开 Firefox

或者，如果你在 Windows 上使用 Firefox 尝试浏览在 WSL 中运行的服务器，你可以手动将 Localias 根证书添加到 Firefox 中。如果你使用 WSL，你需要这样做，因为 Windows 上的 Firefox 不从系统信任存储读取。

找到 Localias 使用的根证书路径。如果你在 MacOS 或 Linux 上，运行：

$ localias debug cert
/Users/pd/Library/Application Support/localias/caddy/pki/authorities/local/root.crt

以打印证书路径。

在 WSL 中，你需要使用 wslpath 工具将其转换为 Windows 文件路径：

$ wslpath -w $(localias debug cert)
\\wsl$\Ubuntu-20.04\home\pd\.local\state\localias\caddy\pki\authorities\local\root.crt

将此路径复制到剪贴板。

在 Firefox 中，访问设置 > 隐私与安全 > 安全 > 证书，或访问设置并搜索"证书"。
点击查看证书
在机构标签下，点击导入...。这将打开一个文件选择对话框。
- 在 MacOS 上：按 "Cmd+Shift+G" 打开文件路径对话框。粘贴你之前复制的路径以选择 root.crt。
- 在 Windows 上：在"名称"字段中，粘贴你之前复制的根证书路径。
点击打开。
勾选信任此 CA 以标识网站旁边的复选框，然后点击确定。

现在你应该看到"localias"列为证书颁发机构。如果你访问安全别名，你应该看到证书是受信任的，并且不会显示任何错误或警告。

允许 Localias 在 Linux 上绑定到 443/80 端口

Localias 通过将请求从 80 和 443 端口代理到你的开发服务器来工作。因此，当你运行 Localias 时，它会尝试监听 80 和 443 端口。在 Linux 上，你可能默认不允许这样做 -- 你可能会看到这样的错误：

$ localias run
# ... 一些信息输出
error: loading new config: http app module: start: listening on :443: listen tcp :443: bind: permission denied

或者你可能会注意到启动守护进程并不会导致守护进程运行

$ localias start
$ localias status
daemon is not running

要解决这个问题，在安装或升级 Localias 后，你可以使用 capabilities 来授予 localias 二进制文件在这些特权端口上绑定的权限：

sudo setcap CAP_NET_BIND_SERVICE=+eip $(which localias)

更多信息，请查看 arch 的 capabilities 手册页和这个 Stackoverflow 回答。

错误：localias 无法成功启动

如果你尝试运行 localias run 并看到这个错误：

$ localias run
错误：localias 无法成功启动。很可能有另一个 localias 实例或其他类型的代理或服务器正在监听 443/80 端口，这阻止了另一个实例启动。常见原因：

- 你在另一个终端中运行了 localias 的另一个实例
- 你正在运行像 Caddy、Nginx 或 Apache 这样的代理服务器
- localias 存在 bug

请查看 https://github.com/peterldowns/localias README 获取一些诊断信息和调试方法。

或者你尝试启动守护进程 localias start 但没有守护进程被启动：

$ localias start
$ localias status
守护进程未运行

那么很可能有其他进程绑定了 443/80 端口，阻止 localias 正确启动。localias 只有在能够绑定这些端口时才能启动，因为它需要这些端口来充当代理。

要查找是否有其他 localias 实例正在运行，请使用 ps。在这个例子中，第一个结果是一个 localias 实例，第二个结果是 grep 进程本身。

$ ps aux | grep -i localias
pd               39020   0.0  0.1 409289408  38736 s003  S+    1:42PM   0:00.09 localias run
pd               39198   0.0  0.0 407965536    624 s005  R+    1:47PM   0:00.00 grep -i localias

你可以使用 lsof 查看哪些服务正在监听你的端口。在这个例子中，结果显示有一个 localias 实例同时绑定了 80 端口和 443 端口：

$  lsof -Pn | grep -E '\*:443|\*:80'
localias  39020   pd    9u     IPv6 0xb3abbd50442d943f       0t0                 TCP *:443 (LISTEN)
localias  39020   pd   11u     IPv6 0xb3abbd4b78f6ba3f       0t0                 UDP *:443
localias  39020   pd   12u     IPv6 0xb3abbd50442da23f       0t0                 TCP *:80 (LISTEN)

为了让 localias 启动，你必须终止干扰并绑定这些端口的进程。

一般阅读 / 链接 / 来源

未来工作

用于转储运行配置的守护进程配置命令
命令行控制器的 --json 格式化以及 caddy 日志
显式证书安装的辅助工具
- 如果有 certutil 可用，处理 Firefox？
- 在 wsl2 中运行时，使用 powershell 脚本自动安装 localias 根证书
如果守护进程启动失败，报告错误
更好的日志访问辅助工具
通用代码清理和测试