[特殊字符] Serverpod 4.1.0 全栈项目开发与 Docker 部署规范文档

文章目录

• • [一、 项目架构与目录规划（Serverpod 4.1.0 共享模型架构）](#一、 项目架构与目录规划（Serverpod 4.1.0 共享模型架构）)
  • [二、 Serverpod 4.1.0 共享 Model 开发规范](#二、 Serverpod 4.1.0 共享 Model 开发规范)
  • • [1. 创建共享模块 (Serverpod Module)](#1. 创建共享模块 (Serverpod Module))
    • [2. 在双后端中引用共享模块](#2. 在双后端中引用共享模块)
  • [三、 Serverpod 4.1.0 Docker 打包规范](#三、 Serverpod 4.1.0 Docker 打包规范)
  • • [1. 编写通用 `Dockerfile`](#1. 编写通用 Dockerfile)
    • [2. 本地构建并导出镜像](#2. 本地构建并导出镜像)
  • [四、 服务器容器编排 (`docker-compose.yml`)](#四、 服务器容器编排 (docker-compose.yml))
  • [五、 反向代理与 HTTPS 配置 (Caddyfile)](#五、 反向代理与 HTTPS 配置 (Caddyfile))

本文档基于 Serverpod 4.1.0 最新版本编写，规范了从本地多端工程组织（APP + 管理后台 + 共享 Model + 双后端）、最新 CLI 开发流程、Docker 镜像打包到阿里云服务器容器化部署的全生命周期流程。

---

一、 项目架构与目录规划（Serverpod 4.1.0 共享模型架构）

在 4.1.0 架构中，前端（APP、Web）与后端（Serverpod Services）逻辑解耦。为了让 app_server 和 admin_server 共用同一套数据结构（Entities / Models），我们将共享模型抽离为独立的 Serverpod Module 库：

my_full_project/                 <-- 统一的项目根目录（本地工作区）
│
├── shared_models/               <-- 0. 共享数据模型模块 (Serverpod Module)
│   ├── shared_models_server/    (放置通用的 .yaml 模型描述文件)
│   └── shared_models_client/    (自动生成的共享数据实体代码)
│
├── my_app/                      <-- 1. Flutter 移动端 APP 客户端
│   ├── lib/
│   └── pubspec.yaml
│
├── my_admin_web/                <-- 2. 管理后台前端（Flutter Web / Vue3 / React）
│   ├── lib/ (或 src/)
│   └── pubspec.yaml (或 package.json)
│
├── app_server/                  <-- 3. App 专用的 Serverpod 后端 (依赖 shared_models)
│   ├── app_server/              (Serverpod 服务端代码，监听 8080)
│   └── app_server_client/       (自动生成的客户端 SDK，供 my_app 引用)
│
├── admin_server/                <-- 4. 后台管理专用的 Serverpod 后端 (依赖 shared_models)
│   ├── admin_server/            (Serverpod 服务端代码，监听 8081)
│   └── admin_server_client/     (自动生成的 SDK，供 my_admin_web 引用)
│
└── deploy/                      <-- 5. 服务器统一部署编排目录
    ├── docker-compose.yml       
    ├── app_config/              (app_server 的 production.yaml)
    └── admin_config/            (admin_server 的 production.yaml)

---

二、 Serverpod 4.1.0 共享 Model 开发规范

1. 创建共享模块 (Serverpod Module)

在项目根目录下运行 Serverpod 4.1.0 命令：

serverpod create shared_models --template module

在 shared_models/shared_models_server/lib/src/protocol/ 中定义所有公共 .yaml 模型（如 user.yaml, order.yaml）。

2. 在双后端中引用共享模块

分别在 app_server/app_server/pubspec.yaml 和 admin_server/admin_server/pubspec.yaml 中引入：

dependencies:
  serverpod: ^4.1.0
  shared_models_server:
    path: ../../shared_models/shared_models_server

在各自的 config/generator.yaml 中配置模块关联：

modules:
  shared_models:
    nickname: shared

执行代码生成：

serverpod generate

---

三、 Serverpod 4.1.0 Docker 打包规范

在 app_server/app_server/ 和 admin_server/admin_server/ 中编写通用的 Dockerfile。因为使用了共享模块依赖，构建上下文需涵盖根目录：

1. 编写通用 Dockerfile

# --- 阶段一：编译二进制文件 ---
FROM dart:3.12.0 AS build

WORKDIR /app

# 复制共享模块与服务依赖
COPY shared_models /shared_models
COPY app_server/app_server/pubspec.* ./app_server/app_server/
WORKDIR /app/app_server/app_server
RUN dart pub get

COPY app_server/app_server .
RUN dart compile exe bin/main.dart -o serverpod_app

# --- 阶段二：运行镜像 ---
FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY --from=build /app/app_server/app_server/serverpod_app /app/serverpod_app
COPY --from=build /app/app_server/app_server/config /app/config

EXPOSE 8080

ENTRYPOINT ["/app/serverpod_app", "--role=all", "--mode=production"]

2. 本地构建并导出镜像

# 镜像构建（针对 linux/amd64 服务器架构）
docker buildx build --platform linux/amd64 -t my_app_server:latest -f app_server/app_server/Dockerfile .
docker save -o app_server_image.tar my_app_server:latest

docker buildx build --platform linux/amd64 -t my_admin_server:latest -f admin_server/admin_server/Dockerfile .
docker save -o admin_server_image.tar my_admin_server:latest

---

四、 服务器容器编排 (docker-compose.yml)

在服务器部署目录 /opt/server_cluster/ 下新建 docker-compose.yml：

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: shared_postgres
    restart: always
    environment:
      POSTGRES_DB: main_db
      POSTGRES_USER: db_user
      POSTGRES_PASSWORD: secure_password_here
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - cluster_net

  redis:
    image: redis:alpine
    container_name: shared_redis
    restart: always
    networks:
      - cluster_net

  app_server:
    image: my_app_server:latest
    container_name: app_server_container
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./app_config:/app/config
    depends_on:
      - postgres
      - redis
    networks:
      - cluster_net

  admin_server:
    image: my_admin_server:latest
    container_name: admin_server_container
    restart: always
    ports:
      - "8081:8080"
    volumes:
      - ./admin_config:/app/config
    depends_on:
      - postgres
      - redis
    networks:
      - cluster_net

volumes:
  postgres_data:

networks:
  cluster_net:
    driver: bridge

---

五、 反向代理与 HTTPS 配置 (Caddyfile)

修改服务器端的 /etc/caddy/Caddyfile：

# APP 端 Backend 接口域名
api.yourdomain.com {
    reverse_proxy localhost:8080 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

# 管理后台 Backend 接口域名
admin-api.yourdomain.com {
    reverse_proxy localhost:8081 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

部署启动命令：

# 启动容器集群
docker compose up -d

# 执行数据库自动迁移
docker exec -it app_server_container /app/serverpod_app --apply-migrations --mode=production

# 热重载 Caddy
sudo systemctl reload caddy