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 会显式地做同样的事情，并且始终是安全的 —— 每一步都是幂等的。

平台支持

平台	信任存储	提权方式
macOS	系统钥匙串 (security add-trusted-cert)	sudo / osascript
Linux	update-ca-trust / update-ca-certificates / trust extract-compat	sudo / pkexec
Windows	通过 crypt32.dll 操作的 ROOT 系统存储	UAC (PowerShell RunAs)

已检测的 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 都可以工作。

命令

命令	用途
install	一次性：CA + 信任 + 守护进程服务 + 菜单栏自启动。传递 --no-service 仅执行 CA 操作。
add <名称> <目标>	添加路由。将 127.0.0.1 条目追加到 /etc/hosts。
remove <名称>	移除路由及其 /etc/hosts 条目。
list	列出存储中的路由。
tui	启动 TUI（也是不带参数运行时的默认行为）。
daemon serve	在前台运行守护进程（通常由服务单元驱动）。
daemon stop	停止正在运行的守护进程并禁用用户服务。
daemon status	报告服务的安装/启用/运行状态。
bar	启动菜单栏应用。由 install 自动启动。
uninstall	取消信任 CA、移除 /etc/hosts 条目、卸载守护进程和菜单栏自启动、清除 ~/.mkdev/。
version	打印版本、提交、构建日期。
completion <bash|zsh|fish|powershell>	输出 shell 自动补全脚本。
hosts-helper	隐藏命令。通过 sudo 调用以原子方式修改 /etc/hosts。

标志和环境变量

标志/环境变量	效果
--home <路径>	覆盖 ~/.mkdev 状态目录。
--verbose, -v	将调试级别日志输出到标准错误。
--version	打印版本并退出。
MKDEV_HOME=<路径>	等同于 --home。

目标格式

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

主机:端口                 例如 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"    # 保留