mkdev

本地开发的真实 HTTPS —— 带 TUI 和局域网共享。

mkdev 在 *.local 上运行受信任的 HTTPS。单个 Go 二进制：证书颁发机构 + 反向代理 + /etc/hosts + mDNS 广播 + 完整的 TUI。

它的不同之处在于：

• 局域网共享 将路由标记为共享，从手机或同一 Wi-Fi 上的任何设备访问 https://app.local。
• TUI，不仅仅是 CLI。 实时路由表、请求日志、证书检查、健康诊断。不带参数运行 mkdev 会进入 TUI。
• 强化的特权边界。 在任何提权调用之前，对 sudo 辅助二进制文件进行所有者、可写性和符号链接检查（internal/safeexec）。没有基于 PATH 的影射，没有组可写的快捷方式。
• 按 SNI 签发证书。 按需签发叶子证书，并由显式的 knownHost 允许列表控制。不是通配符，也不是预先生成的。

它能做什么

mkdev install                    # CA + 信任 + 守护进程服务 + 菜单栏自启动
mkdev add myapp localhost:3000   # 路由 https://myapp.local → localhost:3000
curl https://myapp.local         # 本地应用返回 200

install 是一次性操作：生成 CA，将其加入系统信任存储，安装并启用守护进程用户服务（launchd / systemd），注册菜单栏在登录时启动，并在存在 GUI 会话时立即启动菜单栏。守护进程拥有代理；TUI（mkdev 无参数）和 mkdev add | remove | list 通过 ~/.mkdev/daemon.sock 与它通信。

局域网共享

mkdev 的突出功能。将路由共享到同一 Wi-Fi 上的任何设备，使用真正的 TLS —— 没有警告，没有隧道服务。

1. 在 TUI 的“域”选项卡中，选择一条路由并按 s 键将 SHARE 列切换为 LAN。
2. 该路由通过 mDNS 广播为 <name>.local → 本机的局域网 IP。
3. 在手机/第二台笔记本电脑上，访问 https://<name>.local。一旦设备信任 mkdev CA（一次性操作），就不会有警告。

注意事项

• 只有 .local 路由通过 mDNS 广播。其他 TLD 仍可代理，但不能通过名称在局域网内访问。
• 企业/云 Wi-Fi 通常会阻止多播。家庭和办公室 Wi-Fi 可以工作。
• 切换 s 是实时的 —— mDNS 广播和局域网 ACL 会在下一次请求时更新。无需重启。
• 非共享路由会以深度防御的方式拒绝非环回请求（返回 403）。
• 局域网上的任何人都可以访问您的共享路由。请勿在不信任的 Wi-Fi 上启用。

安装

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

后续升级：

brew update
brew upgrade mkdev

Go

go install github.com/venkatkrishna07/mkdev/cmd/mkdev@latest

升级到特定版本：

go install github.com/venkatkrishna07/mkdev/cmd/[email protected]

直接下载

macOS（Intel + Apple Silicon）、Linux（amd64 + arm64）和 Windows（amd64）的预构建二进制文件发布在 Releases 页面上。每个版本都包含 checksums.txt 以及一个 cosign 无密钥签名（checksums.txt.sig + .pem）—— 有关验证命令，请参见 SECURITY.md#verifying-releases。

在 macOS 上，如果 Gatekeeper 阻止直接下载的二进制文件：

xattr -d com.apple.quarantine ./mkdev

从源码编译

git clone https://github.com/venkatkrishna07/mkdev.git
cd mkdev
task build
cp bin/mkdev ~/bin/        # 或 /usr/local/bin

需要 Go 1.25+。

首次运行

mkdev install   # CA、信任、守护进程服务、菜单栏自启动 —— 一条命令
mkdev           # 启动 TUI

执行 install 后，守护进程在后台运行，菜单栏出现（macOS、Linux GNOME/KDE、Windows）。菜单栏显示守护进程状态、路由列表以及每个路由的启用/局域网共享切换；选择“退出”会退出菜单栏，但不会停止守护进程。

菜单栏

菜单栏是常驻 UI。它位于系统托盘，通过 ~/.mkdev/daemon.sock 与守护进程通信。在登录时自动启动（由 install 注册的自动启动）；也可以通过 mkdev bar 在前台运行。

它显示的内容：

• 状态点 —— 绿色代表正常运行，红色代表故障，黄色代表正在探测，灰色代表关闭。反映守护进程健康状况。
• 标题 —— mkdev v0.4.0 + 守护进程 PID + 运行时间 + 监听代理端口。
• 路由 —— 存储中的所有路由，按顺序从上到下显示。每条条目显示 名称.tld → 目标 以及后缀标签（ · 已禁用、 · LAN）。

它的操作（点击路由）：

• 在浏览器中打开 —— 使用系统默认处理程序打开 https://名称.tld。
• 复制 URL —— 将代理 URL 复制到剪贴板（pbcopy / wl-copy / xclip / clip.exe）。
• 启用/禁用 —— 切换路由的 Enabled 标志。禁用的路由仍保留在存储中，但不再被代理。
• 在局域网共享 —— 切换 mDNS 广播和局域网 ACL。

菜单栏级别的操作：

• 停止守护进程 —— 首先调用 DisableUnit，以便 launchd / systemd 的 KeepAlive 不会立即重新生成它，然后通过套接字发送关闭命令。
• 退出 —— 仅退出菜单栏进程。守护进程和代理继续运行。

注意：

• 不能同时运行两个菜单栏实例（PID 文件锁定；第二个会立即退出）。
• 守护进程重启时，菜单栏会自动重新连接。状态点无需手动刷新即可更新。
• 只有菜单栏（和 mkdev daemon stop）能干净地停止被监督的守护进程 —— 直接杀死守护进程进程会导致被 launchd / systemd 重新生成。

升级

替换二进制文件（brew upgrade / go install ...@latest / 新下载）。下次运行任何 mkdev 子命令时，二进制文件会协调其外部的部分：重写守护进程的 plist / systemd 单元文件和菜单栏自启动条目，使其指向新的二进制文件；重新声明已启用路由的 /etc/hosts 条目；如果 CA 被丢弃，则重新信任它。sudo 提示会内联运行。如果你只运行守护进程而不使用 CLI，守护进程会在其自身启动时执行安全的（无需 sudo）部分，并将其余部分排队等待下一次 CLI 命令。

重新运行 mkdev install 会显式地做同样的事情，并且始终是安全的 —— 每一步都是幂等的。

平台支持

已检测的 Linux 发行版：Debian/Ubuntu (/usr/local/share/ca-certificates)、RHEL/Fedora (/etc/pki/ca-trust/source/anchors)、Arch (/etc/ca-certificates/trust-source/anchors)、openSUSE (/usr/share/pki/trust/anchors)。

Firefox 使用自己的 NSS 存储，目前尚未覆盖 —— 系统 Chrome/Safari/Edge/curl/wget 都可以工作。

命令

标志和环境变量

目标格式

<目标> 接受以下任意格式：

主机:端口                 例如 localhost:3000
http://主机[:端口]/路径   例如 http://localhost:3000/api
https://主机[:端口]/路径  例如 https://gitlab.example.com

对于 HTTPS 上游（例如企业 VPN 上的私有 GitLab），上游的 TLS 证书必须能通过系统信任存储验证。私有 CA 需要将其根证书添加到操作系统钥匙串中。

hosts-helper 不应直接调用。add/remove 会在 sudo 下重新调用同一个二进制文件，以执行需要特权的 /etc/hosts 写入操作。

配置

TLD 注意。 .local 路由需要 mDNS 响应程序（macOS 上始终开启，Linux 上安装 nss-mdns 后可用）。.test / .dev / .localhost 可以在任何地方通过 /etc/hosts 单独使用。在配置中设置 tld 以匹配。

配置文件位于 ~/.mkdev/config.toml。默认值：

tld           = ".local"   # 在 `add` 中的裸名称后追加
proxy_port    = 443        # 绑定 :443 需要在服务端提权
theme         = "auto"     # 为将来 TUI 保留
log_retention = "7d"       # 保留
log_max_size  = "100MB"    # 保留

通过 --home <路径> 或 MKDEV_HOME=... 覆盖配置目录。

工作原理

• 在 ~/.mkdev/ca/ 下生成一个 ECDSA P-256 根 CA。私钥模式为 0o400。
• 将 CA 安装到操作系统原生信任存储中：macOS 钥匙串（security）、Linux CA 捆绑目录 + update-ca-*、Windows 通过 crypt32.dll 的 ROOT 存储。信任存储集成改编自 mkcert（BSD-3）—— 参见 LICENSE-MKCERT。
• 执行 add 时，守护进程将一条路由写入 ~/.mkdev/state.db 的 bbolt KV 存储，并通过一个通过 sudo 调用的辅助子命令将 127.0.0.1 <名称>.<tld> 行追加到 /etc/hosts。
• 守护进程在 0.0.0.0:<proxy_port> 上监听 TLS，（使用根 CA），并反向代理到配置的上游。

安全性

此工具会将一个私有 CA 安装到您的系统信任存储中。任何对 ~/.mkdev/ca/rootCA-key.pem 有读取权限的人都可以签发您的机器会信任的 TLS 证书。密钥以 0o400（仅拥有者可读）创建。

• 代理绑定 0.0.0.0，但连接源 ACL 会对所有未显式标记为 共享 的路由的局域网请求返回 403。回环始终通过。
• 无遥测。无远程调用。无更新检查。
• add/remove 调用 sudo 来修改 /etc/hosts。有关威胁模型以及关于 os.Executable() 解析辅助路径的已知限制，请参见 SECURITY.md。

卸载

mkdev uninstall   # 停止并禁用守护进程、取消信任 CA、清除 /etc/hosts、
                  # 移除守护进程服务和菜单栏自启动、清除 ~/.mkdev/

如果出现卡住的情况，打开钥匙串访问.app，搜索 mkdev，手动删除。然后执行 grep mkdev /etc/hosts 并清理任何残留项。

守护进程和 API

守护进程拥有代理和路由存储。它在 ~/.mkdev/daemon.sock（仅拥有者可读写 0600）上暴露一个本地 HTTP API。TUI、CLI 子命令和菜单栏都是守护进程的客户端 —— 只有守护进程持有 bbolt 锁。

mkdev install 将守护进程安装为用户服务（macOS 上的 launchd LaunchAgent，Linux 上的 systemd --user）并启用它。它在后台运行，并在注销/登录后仍然存活。

mkdev daemon status                # 已安装 / 已启用 / 正在运行
mkdev daemon stop                  # 停止并禁用（防止重新生成）
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/status
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/routes
curl --unix-socket ~/.mkdev/daemon.sock -X POST http://x/v1/routes \
     -H 'Content-Type: application/json' \
     -d '{"name":"foo","target":"localhost:3000"}'
curl --unix-socket ~/.mkdev/daemon.sock -X DELETE http://x/v1/routes/foo

路线图

下一步：

• Firefox / NSS 信任存储集成。
• 按路径路由（/api → 8080，/ws → 9000 在同一域名上）。

故障排除

• Firefox 显示红色警告栏。 Firefox 使用自己的 NSS 存储；系统信任不会传递给它。NSS 集成已在路线图中。目前，请手动导入 ~/.mkdev/ca/rootCA.pem，路径为：设置 → 隐私与安全 → 证书 → 查看证书 → 证书颁发机构 → 导入。
• 守护进程绑定 :443 失败。 macOS/Linux 允许非 root 用户服务通过 launchd / systemd 功能绑定 :443。如果您的发行版对此有限制，请在 ~/.mkdev/config.toml 中设置 proxy_port = 8443，并使用 https://名称.local:8443。
• mkdev add 持续要求输入 sudo 密码。 Sudo 的每个会话缓存会过期（默认 5 分钟）。请改用 TUI 的“域”选项卡 —— 它通过 osascript（macOS GUI 提示）或 pkexec（Linux Polkit）提权。
• /etc/hosts 中已有该名称的条目。 mkdev add 是幂等的，仅当不存在 mkdev 管理的条目时才追加。请手动移除之前的条目或选择不同的名称。

贡献

参见 CONTRIBUTING.md。

致谢

mkdev 的信任存储集成 —— macOS 上的 Keychain/security、Linux 上的 CA 捆绑 + update-ca-*、Windows 上的 crypt32.dll ROOT 存储，以及 NSS 相关路径 —— 改编自 Filippo Valsorda 的 mkcert（BSD-3）。没有这些先前的成果，这个项目将困难得多。上游许可证见 LICENSE-MKCERT。

TUI 使用 Charmbracelet 的 Bubble Tea / Bubbles / Lipgloss 构建。mDNS 通过 hashicorp/mdns。本地 KV 通过 bbolt。

许可证

MIT LICENSE。