安装

下载

在 下载页面 获取最新版本：

系统	文件
macOS（Apple 芯片和 Intel）	.dmg：把 Joppa 拖到“应用程序”中
Linux x86_64	.AppImage（便携版，需先设为可执行：chmod +x joppa-*-amd64.AppImage）或 .deb（Debian、Ubuntu：sudo apt install ./joppa-*-amd64.deb）
Arch Linux x86_64	joppa-bin 软件包，由 makepkg 构建（在空文件夹中）：curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si。再次运行即可更新

在 macOS 上首次打开

Joppa 暂未经过 Apple 签名，因此 macOS 会阻止首次打开。这很正常，而且只需操作一次。

1. 从“应用程序”打开 Joppa。macOS 提示未打开“Joppa”：点击 完成，不要点 移到废纸篓。
2. 打开 系统设置 › 隐私与安全性，向下滚动到 安全性。
3. 在“已阻止 Joppa 以保护你的 Mac”旁，点击 仍要打开。
4. 再次点击 仍要打开 确认，然后输入密码或使用触控 ID。

下载页面 用图示展示了这些步骤。

首次启动时，Joppa 会创建配置文件夹和证书颁发机构，并启动 HTTPS 代理。它还会在后台安装 Vite+ 以及 Node LTS 和 bun，供 JavaScript 项目使用（参见 Node、bun 和 PHP 版本）。之后它常驻在菜单栏中：关闭窗口并不会让它停止。在全新的 Mac 上，git 随 Apple 的命令行工具一起提供：新建项目 窗口中的 安装 git 会安装它们（参见从模板新建项目）。

信任证书

Joppa 使用本地证书颁发机构（CA）为每个域名签发证书。要让浏览器显示锁形图标，你的系统必须信任这个颁发机构。这只需做一次，需要输入你的密码。

首次启动时，Joppa 会立即请求：在系统弹出的窗口中输入你的密码即可。如果你取消了，窗口顶部会显示一条横幅提醒：点击 批准。稍后 会隐藏横幅直到下次启动；点击状态栏中的 CA … 未受信任 也能打开同一个按钮，设置 › 证书颁发机构 中也一直有 批准颁发机构。

在 macOS 上，该按钮会把 CA 加入你的登录钥匙串，并写入你自己的信任设置（Safari 和 Chrome 会读取它）；下面的命令则会把它加入系统钥匙串。

更喜欢用终端？设置中也会显示适用于你这台机器的确切命令，并附有复制按钮。

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  "$HOME/Library/Application Support/joppa/ca/rootCA.pem"

Joppa 会自动检查信任状态：完成后，状态栏会变为 CA joppa 正常。

Linux

批准按钮会为你的发行版选择正确的文件夹。手动操作：

Debian、Ubuntu：

sudo cp ~/.config/joppa/ca/rootCA.pem /usr/local/share/ca-certificates/joppa-rootCA.crt
sudo update-ca-certificates

Arch、Manjaro：

sudo cp ~/.config/joppa/ca/rootCA.pem /etc/ca-certificates/trust-source/anchors/joppa-rootCA.crt
sudo update-ca-trust

Fedora：

sudo cp ~/.config/joppa/ca/rootCA.pem /etc/pki/ca-trust/source/anchors/joppa-rootCA.crt
sudo update-ca-trust

80 和 443 端口

代理监听 127.0.0.1 的 443 端口（HTTPS）和 80 端口（重定向到 HTTPS）。它只接受来自本机的连接。

• macOS：无需任何操作。
• Linux：1024 以下的端口需要特殊权限。如果 Joppa 无法打开这些端口，它会显示要运行的命令：

sudo setcap cap_net_bind_service=+ep /path/to/joppa

如果端口已被其他服务器占用（Lerd、Laravel Herd、Valet、Apache、DDEV、某个容器…），红色横幅会指出它的名字，并提议妥善地停止它：参见 80 和 443 端口被占用。如果只有 80 端口不可用，代理仍会运行；只是 HTTP → HTTPS 重定向会被停用。

解析 .test 域名

浏览器需要知道 myproject.test 指向你的机器。Joppa 会处理这件事：它内置一个小型 DNS 服务器，在 127.0.0.1:15353 上为所有以 .test 结尾的名称返回 127.0.0.1（以及 ::1），并且只响应这些名称。剩下要做的只是告诉系统把这些名称交给它，这需要一个文件，用你的密码写入一次即可。

首次启动时，如果 .test 还无法解析，Joppa 会在批准证书之后立即请求：在系统弹出的窗口中输入你的密码即可。如果你取消了，会有一条横幅提醒（配置）；点击状态栏中的 .test 无法解析 也能打开同一个按钮，设置 › .test 解析 中也一直保留着它。

系统	Joppa 写入的文件
macOS	/etc/resolver/test：nameserver 127.0.0.1 和 port 15353
使用 systemd-resolved 的 Linux（Ubuntu、Fedora…）	/etc/systemd/resolved.conf.d/joppa.conf：DNS=127.0.0.1:15353 和路由域 ~test
使用 NetworkManager 和 dnsmasq 的 Linux	/etc/NetworkManager/dnsmasq.d/joppa.conf：server=/test/127.0.0.1#15353

随后 Joppa 会清空系统的 DNS 缓存（或重新加载 systemd-resolved / NetworkManager）。只有以 .test 结尾的名称会经过它：你的其他 DNS 设置不受影响。

更喜欢用终端？设置 › .test 解析 会显示适用于你这台机器的确切命令，并附有复制按钮。在 macOS 上：

sudo mkdir -p /etc/resolver
printf '# Joppa\nnameserver 127.0.0.1\nport 15353\n' | sudo tee /etc/resolver/test
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

在既没有 systemd-resolved、也没有带 dnsmasq 的 NetworkManager 的 Linux 上，Joppa 无法配置解析器：请把每个域名添加到 /etc/hosts（127.0.0.1 myproject.test）。

容器运行时（可选）

域名和 HTTPS 不需要其他任何东西。如需使用 服务（PostgreSQL、Redis、Mailpit…），请安装以下运行时之一：OrbStack、Docker Desktop、Colima 或 Podman。参见 容器运行时。

检查

窗口底部的状态栏汇总了一切：

joppa   代理 :443   CA joppa 正常   .test 正常   2/2 个域名在线   1/1 个服务

接下来可以阅读 快速上手。

更新

Joppa 会在启动时和每次重新打开窗口时检查新版本，之后每六小时检查一次，并在后台下载。随后侧边栏底部会出现一张绿色卡片：“Joppa x.y.z 已就绪”。点击 立即更新：Joppa 会安装新版本并重启。

每次下载都会先用 Joppa 的签名校验，然后才会替换应用。如果想自己决定何时下载，可以在 设置 › 更新 中关闭 自动下载新版本：卡片会改为提供 下载并安装。同一位置的 检查更新 会立即检查。

在 Linux 上，AppImage 以相同方式更新。通过 .deb 或 Arch 软件包安装的版本无法自行替换：卡片会打开下载页面。在 Arch 上，请在同一文件夹中再次运行 curl -LO https://download.getjoppa.com/latest/PKGBUILD && makepkg -si。

卸载

Joppa 可以在应用中或终端中卸载；两种方式都由你选择要移除的内容，你的项目不会被改动。

• 在应用中：设置 › 卸载 › 卸载 Joppa…，勾选要移除的项，然后点击 卸载并退出。
• 在终端中：

joppa uninstall --dry-run   # 查看将移除的内容
joppa uninstall             # 先请求确认

会移除：joppa 命令、AI 助手的 MCP 服务器、shell 配置中的 PHP 和 Node 代码块、服务的容器、CA 信任和 .test 解析文件（需要你的密码）、许可证（释放这台 Mac 的席位）、Joppa 文件夹以及应用本身。服务的数据（数据库、邮件）只有在你勾选或使用 --volumes 时才会删除。详情参见文件和文件夹 › 完全移除和joppa 命令 › 卸载。