概念

总览

浏览器 ── https://app.myproject.test ──▶ Joppa 代理 (:443, TLS)
                                               │  由本地 CA 签发的证书
                                               ├──▶ localhost:5173   开发服务器 (Vite)
                                               └──▶ localhost:8000   API (Laravel)
                                                         │
                                                         ▼
                                         PostgreSQL / Redis / Mailpit…
                                         (Docker 或 Podman 容器)

项目

项目是 Joppa 知道的一个磁盘文件夹：有名称、图标、域名，还可以有进程、环境变量和固定的版本。名称是域名的基础：项目 kinosante 会获得 kinosante.test 及其子域名。

从 Joppa 移除项目永远不会删除它的文件夹。

域名

域名把一个 https://…test 地址连接到一个本地端口：https://api.kinosante.test → localhost:8000。项目有几个开发服务器，就有几个域名。每个域名都可以停用而不删除。

.test 顶级域名由 IETF 保留用于测试：它永远不会在互联网上分配，因此不会与真实网站冲突。

代理

代理是 Joppa 内置的 HTTPS 反向代理。它监听 127.0.0.1 的 443 和 80 端口，根据请求的名称选择对应的证书，再把请求转发到该域名的端口。它支持 HTTP/2、WebSocket（HMR）和 Server-Sent Events。参见 HTTPS 代理。

证书颁发机构

本地证书颁发机构（CA）为每个域名即时签发证书。一旦系统信任了它，所有现有和将来的域名都会受信任。参见 证书。

进程

进程是 Joppa 为项目运行的一条命令：package.json 中的 dev 脚本，或项目的某个 Docker Compose 服务。Joppa 知道它们的顺序和端口，并会重新启动崩溃的进程。参见 进程。

服务

服务是 Joppa 在容器中运行的共享服务器：PostgreSQL、MySQL、MariaDB、Redis、Valkey、Mailpit、Typesense 或 Meilisearch。一个服务器为你所有的项目服务；对于数据库，每个项目都有自己的数据库。把服务关联到项目时，会将其变量写入 .env。参见 服务。

容器运行时

运行时是运行服务容器的工具：OrbStack、Docker Desktop、Colima 或 Podman。只有服务才需要它。参见 容器运行时。

应用、终端和 AI 助手

桌面应用是 Joppa 的核心：它运行代理并保存状态。joppa 命令、它的 TUI 和 MCP 服务器 都通过本地 API 与正在运行的应用通信；它们能做的事与窗口相同。