serverpod-overview

Serverpod 概览

Serverpod 是一个使用 Dart 编写、面向 Flutter 的开源后端框架。一个 Serverpod 项目通常由三个软件包组成：

my_project_server - 服务端代码。 my_project_client - 生成的客户端代码。 my_project_flutter - Flutter 应用（导入客户端）。

项目还可以包含用于共享代码的软件包，例如 my_project_shared。

服务端从 lib/server.dart 启动。该文件通过 final pod = Serverpod(args);，从 src/generated/serverpod.dart 创建生成的 Serverpod 类（已预先接入项目的协议和端点），然后执行 await pod.start();。

服务端会公开端点类，客户端通过生成的 RPC 客户端调用这些端点。向端点添加方法后，代码生成会在客户端重新生成对应方法。模型使用 YAML 定义，并会为服务端和客户端生成 Dart 类。

Serverpod 项目使用 PostgreSQL 数据库进行持久化（也支持 SQLite），并内置 ORM、缓存、实时流式传输（使用 Dart 流）、文件上传、调度（称为 future calls）、日志记录以及内置 Web 服务（Relic）。

这些功能各自都有对应的 serverpod-* 技能；请根据任务选用合适的技能。Insights 配套应用不在技能覆盖范围内，相关文档请参阅 https://docs.serverpod.dev。

运行服务端

开发环境由 Serverpod runner 启动，每个服务端软件包对应一个后台进程。它会生成代码、通过热重载编译服务端、启动配套 Flutter 应用，并提供 serverpod MCP 服务。运行期间，它会监视文件变更，以执行增量代码生成并热重载服务端（如果项目包含 Flutter 应用，也会热重载该应用）。

• serverpod start 确保 runner 正在运行；若没有运行，则会启动一个并连接到它：在终端中显示交互式终端 UI，否则显示普通日志流，或在使用 --no-tui 时显示普通日志流。该命令会一直运行，直到用户退出。如果退出时 runner 是由 start 启动的，它会停止；如果连接的是已在运行的 runner，则会继续运行。这是用户要运行的命令。serverpod start --no-attach 的行为与 serverpod runner start 相同。
• serverpod runner start 以相同方式确保 runner 正在运行，打印其地址后返回，并让它在后台继续运行。这是启动 runner 的方式。冷启动会编译整个项目，可能需要几分钟。声明了 auto_launch 的配套 Flutter 应用会在 UI 连接后启动；在此之前，可使用 MCP 工具 spawn_flutter_app 启动任意应用。
• serverpod runner attach 会像 serverpod start 一样连接到已在运行的 runner，并显示 UI，且不会启动新的 runner。退出后 runner 会继续运行。
• serverpod runner status 会显示 runner 是正在启动、正在运行、正在停止，还是项目构建失败但 runner 仍在运行；还会显示 API、Insights 和 Web URL，以及日志路径。
• serverpod runner stop 会停止 runner。

这些命令都会从当前目录解析服务端软件包，也可以通过 --directory <server package>（-d）指定。

执行操作前不要检查服务端是否正在运行：直接进行更改并调用 serverpod MCP 工具。如果没有任何服务在运行，MCP 会返回明确的“the server is not running”错误。此时：

1. 调用 tail_runner_logs，了解 runner 是否仍在启动，或它停止的原因。
2. 如果没有 runner 正在运行，请在服务端软件包目录中运行 serverpod runner start。服务端启动后，该命令会以零状态码返回。如果项目无法构建、已配置的端口被非 Serverpod runner 的程序占用，或 Docker 拒绝操作，该命令会以非零状态码返回。项目无法构建时，runner 会继续运行，并且在开启监视（默认开启）的情况下，会在更改使项目能够构建后启动服务端。请修复原因，不要重试。唯一的例外是：如果 shell 在 serverpod runner start 返回前因超时将其终止，runner 会继续在后台启动，再次运行该命令会等待它启动。
3. 再次调用 MCP 工具。MCP 会自行重新连接。 完成后请让 runner 继续运行；用户会使用 serverpod start 连接到它。只有在收到请求时才运行 serverpod runner stop。如果使用 --watch、--target、--flutter、--docker，或与正在运行的 runner 不同的服务器参数启动堆栈，启动会失败并指出差异；请先停止该 runner。

以下任务 ALWAYS 使用 MCP 服务，而不是命令行。serverpod runner 命令是例外；它们用于管理堆栈本身。运行中的 runner 会提供：

• create_migration 和 apply_migrations，用于数据库操作（更改数据模型后使用）。
• create_repair_migration，用于数据库与迁移不同步的情况。它只会写入修复文件；之后请运行 apply_migrations。
• tail_server_logs，用于读取服务器日志。
• tail_runner_logs，用于读取 runner 本身的输出（代码生成、编译、Docker、服务器原始输出）。这是唯一一个在服务器启动期间或停止后仍可使用的工具。
• tail_flutter_logs，用于读取 Flutter 应用的原始 stdout/stderr。
• hot_reload，用于重新加载服务器和 Flutter 应用，同时保留内存状态。仅在使用 --no-watch 时需要，因为 runner 会在文件更改时重新加载。
• hot_restart，用于重启服务器和 Flutter 应用，并丢弃内存状态。在 Flutter 应用中进行可能无法通过常规热重载（会自动应用）生效的更改后，ALWAYS 调用此工具。
• spawn_flutter_app，用于启动服务器 pubspec.yaml 中 serverpod: flutter_apps: 下声明的 Flutter 应用。
• get_flutter_app_dtd，用于获取正在运行的 Flutter 应用的 Dart Tooling Daemon URI。将其传递给 dart MCP 以驱动应用。

面向 Flutter 应用的工具接受可选参数 appId，其值为 serverpod: flutter_apps: 下的映射键。仅当项目声明了多个应用时才需要此参数。

同时运行多个服务

每个服务包恰好有一个运行器，以包目录为标识：其清单、锁文件、日志和套接字都位于 <server package>/.dart_tool/serverpod/，每个运行器都会在 ~/.serverpod/runners/ 下注册。因此，包含多个服务包的工作区，以及同一项目的多个检出版本或工作树，各自都会运行自己的运行器。使用 serverpod runner start --directory <server package> 启动每个运行器。一个 MCP 桥接服务只服务于一个服务包，因此 Agent 配置需要为每个服务分别配置一条 serverpod mcp-server --server-dir <server package> 条目。桥接服务服务的是其 --server-dir 指定的包，而不是当前所在目录，并会在其说明和错误消息中指出服务对象。若要从另一个检出版本或工作树应用迁移或重启，请先确认这一点。

这些包通常共用一个 config/development.yaml，其中端口相同（8080、8081、8082）。第一个运行器会绑定这些端口。若运行器发现这些端口已被另一个运行器占用，它会将所有监听端口一起改为临时端口；只要这些端口仍空闲，运行器重启时就会继续使用它们。切勿假定地址是 localhost:8080：请从 serverpod runner status 或 serverpod runner start 的输出中读取地址。运行器启动的 Flutter 应用会通过 --dart-define=SERVER_URL=... 获得正确的 URL；手动启动的应用、浏览器标签页或 curl 必须使用 status 中的地址。

若配置的端口被非 Serverpod 运行器占用，例如通过 dart run bin/main.dart 手动启动的服务，则属于错误：请停止该进程，或更改 config/development.yaml 中的端口。

嵌入式 PostgreSQL（database.dataPath）按检出版本隔离。它通过 Unix 套接字监听；当运行模式配置了数据库密码时，也会在回环 TCP 的 database.port 上监听。这是第四个监听端口：它会和服务端口一起改用其他端口，且 status 会打印数据库地址。若此检出版本已通过 serverpod database start 启动数据库，则会连接到该数据库，而不会更换端口。只有使用 Docker Compose 数据库的项目会共用主机端口；Compose 项目以服务目录命名，因此此类项目的两个检出版本会共用同一组容器。仅当没有其他检出版本正在使用该共享 Compose 栈时，才启动使用此共享 Compose 栈的检出版本。否则，请保持现有栈运行，并且不要启动此检出版本的运行器，除非用户明确要求切换检出版本。

项目没有运行实例时的操作

• MCP 可用时，绝不要运行 serverpod generate 或 serverpod create-migration：运行器会在保存时生成代码，MCP 会创建迁移。serverpod runner 命令管理整个栈，始终可以运行。
• 仅当 MCP 不可用，或 serverpod runner start 无法启动服务时，才通过调用 serverpod generate 生成代码。
• 绝不要编辑生成的代码，因为下次生成时这些修改会被覆盖。此限制不适用于已创建迁移的 SQL；SQL 可以编辑，详见 Serverpod Migrations 技能。

生成代码后，可以通过调用 serverpod create-migration 创建数据库迁移。仅当无法使用 MCP 时才使用。

# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]

有关更多详情，请参阅 Serverpod Migrations 技能。

更改后的检查清单：

1. dart analyze（命令行，或 dart MCP 服务）
2. dart format（命令行，或 dart MCP 服务）
3. 如有需要，执行 serverpod MCP 的 hot_restart（热重载会自动完成）。这也会热重启 Flutter 应用
4. 检查 serverpod MCP 的 tail_server_logs（若有 Flutter 应用，也检查 tail_flutter_logs），查看是否存在问题