serverpod-configuration

Serverpod 配置

优先级（从高到低）：Dart 配置对象 > 环境变量 > YAML 配置文件。配置使用位于 config/ 中的 YAML 文件。密钥位于 config/passwords.yaml，或使用带 SERVERPOD_PASSWORD_ 前缀的环境变量。

运行模式

各模式的配置文件：config/development.yaml、config/staging.yaml、config/production.yaml、config/test.yaml。启动服务时通过 --mode 设置，或使用 SERVERPOD_RUN_MODE（默认值：development）。

API 服务（最低配置）

apiServer:
  port: 8080
  publicHost: localhost
  publicPort: 8080
  publicScheme: http

port 是监听器绑定的端口。publicHost/publicPort/publicScheme 用于生成返回给客户端的 URL；publicPort 为 0 时会使用绑定的端口。

在开发环境中，Serverpod runner 会保留配置的端口，除非机器上的另一个 runner 正在占用这些端口；遇到这种情况时，它会绑定临时端口（通过 SERVERPOD_API_SERVER_PORT、其同类变量以及 SERVERPOD_DATABASE_PORT；api、insights 和 web 监听器的 _PUBLIC_PORT 变量会使用相同的值，因此返回给客户端的 URL 会使用绑定的端口），并在 serverpod runner status 中公布实际地址。请参阅概览技能中的同时运行多个服务。

数据库

可以使用 PostgreSQL 或 SQLite 作为数据库。

PostgreSQL

database:
  host: localhost
  port: 8090
  name: my_project
  user: postgres
  dataPath: .serverpod/development/pgdata  # embedded database, see below

密码位于 passwords.yaml 中对应运行模式的配置下，或设置为 SERVERPOD_PASSWORD_database。可选项：searchPaths、maxConnectionCount、requireSsl、isUnixSocket。

**嵌入式 PostgreSQL：**设置 dataPath 后，Serverpod 会在该目录中启动并管理 PostgreSQL 实例，因此无需单独安装或运行。新项目会在开发和测试中使用它。它会监听自己的 Unix 套接字；当运行模式中设置了数据库密码时，也会监听 port 上的环回 TCP 连接。在开发环境中，如果另一个 Serverpod runner 正在占用该端口，runner 会像处理服务端口一样为数据库端口换用其他端口，因此多个检出副本可以同时各自运行。serverpod database start [--mode <mode>] [--port <port>] 可独立启动同一个数据库（不启动服务），也可以连接到服务已经启动的数据库。

未设置 dataPath 时，数据库为外部数据库；如果项目有 compose 文件且 PostgreSQL 位于 localhost，runner（serverpod start）会启动 Docker Compose 服务（--docker / --no-docker 可覆盖此行为）。

SQLite

database:
  filePath: my_project.sqlite

SQLite 无需密码。

Redis

redis.enabled、redis.host、redis.port；密码通过 SERVERPOD_PASSWORD_redis 设置。

密钥（passwords.yaml）

结构：shared:（适用于所有模式）+ 各模式配置（development:、production: 等）。内置键：database、redis、serviceSecret。自定义键可通过 session.passwords['key'] 或 pod.getPassword('key') 获取。

内置密码也有专用环境变量：SERVERPOD_DATABASE_PASSWORD、SERVERPOD_REDIS_PASSWORD 和 SERVERPOD_SERVICE_SECRET。任何密码，无论是内置还是自定义，都可以使用 SERVERPOD_PASSWORD_ 前缀设置。

export SERVERPOD_PASSWORD_stripeApiKey=sk_live_...  # → session.passwords['stripeApiKey']

切勿提交真实密钥；生产环境请使用环境变量。

generator.yaml

位于 config/generator.yaml：

• type：server（默认值）、module 或 internal
• client_package_path：客户端包的路径
• modules：模块名称映射 + 可选的 nickname
• server_test_tools_path：测试工具输出路径（移除此项可禁用）
• extraClasses：自定义可序列化类 URI
• features：例如 database: true/false

Dart 配置覆盖

将 config: ServerpodConfig(...) 传递给 Serverpod(...)，即可跳过文件/环境变量加载并使用 Dart 配置对象；CLI 标志仍会合并进来。

对于测试，可以使用 configOverride: (config) => config.copyWith(...) 在处理完 YAML/环境变量/CLI 配置后调整已加载的配置。

TLS/SSL

将加载证书链和私钥的 SecurityContext 传递给 Serverpod(...) 中的 SecurityContextConfig。在 apiServer、webServer 和/或 insightsServer 上设置。客户端：将包含受信任证书的 SecurityContext 传递给 Client(...)。

参考文件

• references/environment-variables.md — 完整的 SERVERPOD_* 环境变量表。
• references/flutter-apps.md — 声明 serverpod start 可启动的 Flutter 应用。