serverpod-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serverpod Configuration

Serverpod 配置

Priority (highest wins): Dart config object > environment variables > YAML config files. The config uses YAML files that live in

config/

. Secrets are in

config/passwords.yaml

or env vars with

SERVERPOD_PASSWORD_

prefix.

优先级（最高优先级获胜）：Dart 配置对象 > 环境变量 > YAML 配置文件。配置使用存储在

config/

目录下的YAML文件。密钥存储在

config/passwords.yaml

中，或使用带有

SERVERPOD_PASSWORD_

前缀的环境变量。

Run mode

运行模式

Config files by mode:

config/development.yaml

config/staging.yaml

config/production.yaml

config/test.yaml

. Set via

--mode

when starting server or

SERVERPOD_RUN_MODE

(default:

development

按模式划分的配置文件：

config/development.yaml

、

config/staging.yaml

、

config/production.yaml

、

config/test.yaml

。启动服务器时通过

--mode

参数设置，或使用

SERVERPOD_RUN_MODE

环境变量（默认值：

development

）。

API server (minimum)

API 服务器（最小配置）

yaml

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

publicHost

publicPort

publicScheme

are used for URLs returned to clients.

yaml

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

publicHost

publicPort

publicScheme

用于生成返回给客户端的URL。

Database

数据库

It is possible to use either PostgreSQL or SQLite as the database.

可以选择PostgreSQL或SQLite作为数据库。

PostgreSQL

yaml

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

Password in

passwords.yaml

under run mode or

SERVERPOD_PASSWORD_database

. Optional:

searchPaths

maxConnectionCount

requireSsl

isUnixSocket

Embedded PostgreSQL: with

dataPath

set, Serverpod launches and manages a PostgreSQL instance in that directory, so nothing has to be installed or run separately. New projects use it for development and testing.

serverpod database start [--mode <mode>] [--port <port>]

boots the same database on its own, without the server.

Without

dataPath

the database is external, and

serverpod start

starts Docker Compose services when the project has a compose file and PostgreSQL is on localhost (

--docker

--no-docker

override this).

yaml

database:
  host: localhost
  port: 8090
  name: my_project
  user: postgres
  dataPath: .serverpod/development/pgdata  # 嵌入式数据库，详见下文

密码存储在对应运行模式下的

passwords.yaml

中，或使用

SERVERPOD_PASSWORD_database

环境变量。可选配置：

searchPaths

、

maxConnectionCount

、

requireSsl

、

isUnixSocket

。

嵌入式PostgreSQL： 设置

dataPath

后，Serverpod会在该目录下启动并管理一个PostgreSQL实例，无需单独安装或运行。新项目在开发和测试阶段默认使用该模式。使用

serverpod database start [--mode <mode>] [--port <port>]

命令可以单独启动该数据库，无需启动服务器。

如果未设置

dataPath

，则使用外部数据库。当项目包含compose文件且PostgreSQL位于本地主机时，

serverpod start

会启动Docker Compose服务（可通过

--docker

--no-docker

参数覆盖此行为）。

SQLite

yaml

database:
  filePath: my_project.sqlite

No password is needed for SQLite.

yaml

database:
  filePath: my_project.sqlite

SQLite无需密码。

Redis

redis.enabled

redis.host

redis.port

; password via

SERVERPOD_PASSWORD_redis

配置项包括

redis.enabled

、

redis.host

、

redis.port

；密码通过

SERVERPOD_PASSWORD_redis

环境变量设置。

Secrets (passwords.yaml)

密钥（passwords.yaml）

Structure:

shared:

(all modes) + per-mode (

development:

production:

, etc.). Built-in keys:

database

redis

serviceSecret

. Custom keys available via

session.passwords['key']

pod.getPassword('key')

The built-in passwords also have dedicated environment variables:

SERVERPOD_DATABASE_PASSWORD

SERVERPOD_REDIS_PASSWORD

and

SERVERPOD_SERVICE_SECRET

. Any password, built-in or custom, can also be set with the

SERVERPOD_PASSWORD_

prefix.

bash

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

Never commit real secrets; use env vars in production.

结构：

shared:

（所有模式通用）+ 各模式专属配置（

development:

、

production:

等）。内置密钥项：

database

、

redis

、

serviceSecret

。自定义密钥可通过

session.passwords['key']

或

pod.getPassword('key')

获取。

内置密钥也有对应的专属环境变量：

SERVERPOD_DATABASE_PASSWORD

、

SERVERPOD_REDIS_PASSWORD

和

SERVERPOD_SERVICE_SECRET

。任何内置或自定义密钥都可以使用

SERVERPOD_PASSWORD_

前缀的环境变量设置。

bash

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

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

generator.yaml

config/generator.yaml

```
type
```
:
```
server
```
(default),
```
module
```
, or
```
internal
```
```
client_package_path
```
: path to client package
```
modules
```
: map of module names + optional
```
nickname
```
```
server_test_tools_path
```
: test tools output path (remove to disable)
```
extraClasses
```
: custom serializable class URIs
```
features
```
: e.g.
```
database: true/false
```

位于

config/generator.yaml

中的配置：

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

Dart config override

Dart 配置覆盖

Pass

config: ServerpodConfig(...)

Serverpod(...)

to skip file/env loading and use a Dart config object, with CLI flags still merged in.

For tests, it is possible to use

configOverride: (config) => config.copyWith(...)

to adjust the loaded config after YAML/env/CLI processing.

在

Serverpod(...)

中传入

config: ServerpodConfig(...)

，可跳过文件/环境加载，直接使用Dart配置对象，同时仍会合并CLI标志。

测试时，可使用

configOverride: (config) => config.copyWith(...)

在YAML/环境/CLI处理完成后调整加载的配置。

TLS/SSL

Pass

SecurityContextConfig

Serverpod(...)

with a

SecurityContext

that loads cert chain and private key. Set on

apiServer

webServer

, and/or

insightsServer

. Client: pass

SecurityContext

with trusted certificates to

Client(...)

将

SecurityContextConfig

传入

Serverpod(...)

，其中包含加载证书链和私钥的

SecurityContext

。可在

apiServer

、

webServer

和/或

insightsServer

上设置。客户端需将带有受信任证书的

SecurityContext

传入

Client(...)

。

Reference files

参考文件

references/environment-variables.md

— the full

SERVERPOD_*

environment variable table.

```
references/flutter-apps.md
```
— declaring the Flutter apps that
```
serverpod start
```
can launch.

references/environment-variables.md

—— 完整的

SERVERPOD_*

环境变量列表。

references/flutter-apps.md

—— 声明

serverpod start

可启动的Flutter应用。