服务
将 Joppa 的共享服务（PostgreSQL、Redis、Mailpit…）接入项目：.env 变量在 diff 后写入，以及 Laravel 测试数据库。
服务 标签页（V）将 Joppa 的服务接入项目：PostgreSQL、MySQL、Redis、Mailpit、Meilisearch… 其计数显示已关联的服务数量。一键即可：服务的变量在 diff 之后写入 .env，并跟随其端口。
服务还是进程
标签页在简介下方说明：“服务由 Joppa 在各项目间共享（数据库、缓存、邮件）。项目自身运行的内容在“进程”中。”（查看进程）。
- Joppa 服务 为你的所有项目只运行一次；每个项目在其中有自己的数据库。它在 服务 页面中创建，在这里接入。
- 进程 属于项目：开发服务器、worker、Docker Compose 容器。它在 进程 标签页中管理。
已关联的服务会随「全部启动」最先启动，早于项目的进程。
接入服务
服务区块列出了 Joppa 中的服务。使用 PostgreSQL（或 Redis、Mailpit…）会打开一个 diff，并提供两个选项：
- 关联并写入 .env：写入该服务的变量，并在其端口变化时保持更新。
- 关联但不写入：Joppa 记住这个关联，但不改动文件。
接入的服务如果处于停止状态会立即启动，在添加项目时接受推测出的服务也是如此。对于数据库，如果项目的数据库尚不存在，Joppa 会创建它：服务行会显示“数据库 {名称}，接入时创建”，接入后可通过选择器切换到该服务中的其他数据库；如果所选数据库在服务中不存在，创建会创建它。数据库一经创建，各处的数据库列表（服务页面、测试数据库）会立即更新。一个项目每种类型只使用一个服务：接入 MySQL 会替换 PostgreSQL。
停止使用… 则相反：取消关联并清理 .env 会恢复 .env.example 中的值（或移除该变量），取消关联，不改动 .env 则保持文件原样。你手动修改过的变量会被保留。
接入会写入 .env：如果 .env 编辑器（环境 标签页）有未保存的修改，开关会被禁用（“请先保存或撤销 .env 的修改”）。
变量名
Joppa 会以项目已在读取的名称写入：先是 .env 中的名称，然后是 .env.example 中的名称（即使被注释掉）。它能识别许多别名（DATABASE_URL、DIRECT_URL、POSTGRES_PRISMA_URL、POSTGRES_*、PG*、MYSQL_*…），并保留你现有 URL 的协议和参数。
如果项目没有声明任何变量，Joppa 会使用其框架的常用名称：
| 服务 | Laravel | 其他 |
|---|---|---|
| 数据库 | DB_CONNECTION、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD |
DATABASE_URL（Symfony：带 ?serverVersion=…&charset=utf8） |
| Redis、Valkey | REDIS_HOST、REDIS_PASSWORD、REDIS_PORT |
REDIS_URL |
| Mailpit | MAIL_MAILER=smtp、MAIL_HOST、MAIL_PORT… |
Symfony MAILER_DSN · Rails SMTP_ADDRESS、SMTP_PORT · Django EMAIL_HOST、EMAIL_PORT · Node SMTP_HOST、SMTP_PORT |
| Meilisearch | MEILISEARCH_HOST、MEILISEARCH_KEY、SCOUT_DRIVER |
Symfony MEILISEARCH_URL、MEILISEARCH_API_KEY |
| Typesense | TYPESENSE_*、SCOUT_DRIVER |
TYPESENSE_HOST、TYPESENSE_PORT、TYPESENSE_PROTOCOL、TYPESENSE_API_KEY |
框架通过其文件识别：Laravel（artisan）、Symfony、Django（manage.py）、Rails、Node（package.json）。
推测的服务
Joppa 会读取项目的文件来推测它需要哪些服务，即使没有 Docker Compose。这只是一个提示：未经你确认，不会添加或接入任何服务。
| 服务 | 依据 |
|---|---|
| PostgreSQL、MySQL、MariaDB | DB_CONNECTION（pgsql、mysql、mariadb），DATABASE_URL、DB_URL、POSTGRES_URL 或 MYSQL_URL 的协议，Prisma 的 provider，Drizzle 的 dialect，依赖包 pg、postgres、mysql2、mariadb… |
| Redis、Valkey | 设为 redis 的 Laravel 驱动（CACHE_STORE、SESSION_DRIVER、QUEUE_CONNECTION、BROADCAST_CONNECTION），REDIS_URL、VALKEY_URL，依赖包 predis/predis、laravel/horizon、ioredis、redis、bullmq、iovalkey |
| Meilisearch、Typesense | SCOUT_DRIVER、MEILISEARCH_HOST、TYPESENSE_HOST…，依赖包 meilisearch/meilisearch-php、typesense/typesense-php、meilisearch、typesense |
| Mailpit | 端口 1025 上的本地 SMTP（MAIL_MAILER=smtp 且 MAIL_PORT=1025，或 SMTP_PORT=1025） |
Joppa 会读取 .env，再用 .env.example 补充 .env 中没有的键，还会读取 composer.json、根目录及 apps/*、packages/*、services/* 下的 package.json、prisma/schema.prisma 和 drizzle.config.*。数据库和缓存只保留一个引擎：.env 指定的优先于 schema，schema 优先于依赖包。SQLite 不需要任何服务。单独的 REDIS_HOST 不算数：每个 Laravel 的 .env.example 都会列出它。
结果显示在两个地方：
- 项目页面上的一行提示“此项目似乎使用了 PostgreSQL、Redis 和 Meilisearch。”，附带 在服务中查看；
- 此标签页顶部的“此项目似乎使用了”区块，显示每个服务的发现位置（
.env.example · DB_CONNECTION=pgsql）以及同样可用的引擎（Redis“或 Valkey”，MySQL“或 MariaDB”）。如果 Joppa 已有该引擎的服务，接入 PostgreSQL 18 会打开常规的 diff；否则 添加 Meilisearch 会先创建服务，再将其接入。
PostgreSQL 扩展
对于 PostgreSQL，Joppa 还会查找项目使用的扩展：
.sql文件（Prisma、Drizzle、Supabase 迁移，database/、db/…）和迁移中的CREATE EXTENSION；- Laravel 迁移中的
Schema::ensureVectorExtensionExists()和->vector(（pgvector）、uuid_generate_v4()（uuid-ossp）、gin_trgm_ops（pg_trgm）； - Rails 的
enable_extension "hstore"，Django 的CreateExtension("citext")、TrigramExtension()、VectorExtension()…； - Prisma 的
extensions = [pg_trgm, uuid_ossp(map: "uuid-ossp")]，以及Unsupported("vector(…)")（pgvector）或Unsupported("geometry(…)")（PostGIS）类型； - Compose 镜像：
pgvector/pgvector、postgis/postgis。
只保留 Joppa 能提供的扩展：pgvector、PostGIS、pg_trgm、uuid-ossp、pgcrypto、citext、hstore、unaccent…PostgreSQL 这一行会列出它们（“扩展：pgvector, pg_trgm”）；单凭一条 CREATE EXTENSION 就足以推测出 PostgreSQL。添加 PostgreSQL 会打开创建窗口，并已勾选这些扩展（服务器上以及每个新数据库）。如果所选服务器还缺少需要在服务器上启用的扩展（pgvector、PostGIS…），启用 pgvector 会打开其设置并勾选该扩展，保存即可。只要接入项目的 PostgreSQL 还缺少其中某个扩展，这一行就会保留。
一旦项目使用了同类服务，该服务就会从列表中消失。某一行的叉号会在此项目中忽略该服务；横幅或区块顶部的叉号会忽略全部。项目 Docker Compose 已经运行的服务交由 从 Docker Compose 导入 处理。
测试数据库（Laravel）
Laravel 项目的测试从 phpunit.xml 和 .env.testing 读取数据库。项目有其中之一时，本标签页会显示一个测试数据库区块，说明测试需要什么：
- 测试需要指定的数据库（例如
phpunit.xml设置了DB_CONNECTION=pgsql和DB_DATABASE=shop_testing，往往指向另一个工具）：Joppa 在同一引擎的某个服务中，按这个名称提供该数据库； - 测试在 SQLite 上运行，而应用使用 PostgreSQL、MySQL 或 MariaDB：Joppa 提议让测试在同一引擎上运行，使用数据库
<应用数据库>_test； - 测试没有任何设置：它们会使用应用自己的数据库，而
RefreshDatabase会清空它。Joppa 提议单独建一个<应用数据库>_test数据库。
如果应用和测试都在 SQLite 上运行，就没有可提议的内容，区块不会出现。
服务是项目已在使用的那个（否则是对应引擎的第一个），数据库名称可以修改。创建并关联会在需要时启动服务，在数据库缺失时创建它，并写入 DB_CONNECTION、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME 和 DB_PASSWORD。每个文件都有自己的 diff（查看更改）；已填写的 DB_URL 会被清空，否则它会优先于这些值。
如果文件已指向服务中不存在的数据库，该区块会提示（“数据库 … 尚未在 … 中创建。”），创建数据库会创建它，必要时先启动服务。
| 项目包含 | Joppa 写入 |
|---|---|
.env.testing 和 phpunit.xml |
.env.testing；只有勾选同时修改 phpunit.xml 时才写入 phpunit.xml |
仅 .env.testing |
.env.testing |
仅 phpunit.xml |
phpunit.xml（若只有 phpunit.xml.dist 则写它） |
在 phpunit.xml 中，Joppa 只改动 <env name="DB_…"> 标签：修改它们的 value，取消 Laravel 默认注释掉的标签的注释，并以相同缩进在 <php> 末尾添加缺少的标签。文件其余部分保持不变。首次写入前，每个文件都会在旁边复制一份（phpunit.xml.joppa-backup、.env.testing.joppa-backup）；如果文件在预览后已在磁盘上被修改，则不会覆盖。
添加 Laravel 项目和新建项目时也会提供同样的选择。