1. 构建多平台镜像

1.1 通过 GitHub Actions 构建并推送

你可以使用 GitHub Actions 工作流或其他 CI 工具，构建并推送多平台镜像到 Docker 镜像仓库。

更多细节请参考 .github/workflows/build-and-push.yml 文件。当推送以 “v” 开头的 tag 时触发构建，例如 v1.0.0。

./deploy/Dockerfile 为多阶段 Dockerfile，共三个阶段：

fonts — 通过 deploy/install-font.sh 下载 Noto 字体文件（缓存层，很少变更）
build_stage — 使用 Maven 编译应用 jar
final image — 将字体与 jar 复制到精简 JRE 镜像中

在 GitHub Actions 工作流中，会通过 build args 传入 APP_PATH、APP_NAME 参数。镜像的 version 会从 tag 名中提取，例如 v1.0.0 -> 1.0.0。

./deploy/Dockerfile.ci 为 CI 流水线使用的两阶段变体（jar 已预先构建），包含相同的字体安装阶段。

1.2 本地脚本手动构建并推送

构建镜像并推送到 Docker 镜像仓库。

通过指定 APP_PATH、APP_VERSION 来构建 Java 应用镜像。


./deploy/build.sh <APP_PATH> <APP_VERSION> [<REGISTRY_NAMESPACE>]

其中 APP_PATH 是应用源码目录的相对路径，例如 apps/demo-app。并且 APP_PATH 的最后一段名称就是应用名，例如 demo-app。

REGISTRY_NAMESPACE 为可选参数，默认值是 softa。你可以指定 REGISTRY_NAMESPACE，将镜像推送到你自己的 Docker 镜像仓库。

构建 Demo 应用镜像示例：


./deploy/build.sh apps/demo-app 1.0.3

2. 安装 Noto 字体（PDF 生成）

配合 file-starter 生成 PDF（RICH_TEXT 文档模板）时需要 Noto 字体。 Docker 镜像内已自动安装（见上文）。本地开发请执行：


sh deploy/install-font.sh

脚本会自动检测操作系统字体目录（macOS 为 ~/Library/Fonts，Linux 为 ~/.local/share/fonts）。也可显式指定目标目录：


sh deploy/install-font.sh /path/to/fonts

3. 通过 Docker Compose 启动 EFK（可选）


docker-compose -f deploy/efk/docker-compose.yml up -d

通过 http://localhost:5601 访问 Kibana 控制台。

或者你也可以通过配置 spring.elasticsearch.uris 属性，连接到你自己的 Elasticsearch 集群。

然后使用 demo-app/init_es/create_index 创建索引。

4. 通过 Docker Compose 启动 Pulsar（可选）


docker-compose -f deploy/pulsar/docker-compose.yml up -d

通过 http://localhost:8080 访问 Pulsar 控制台。

或者你也可以通过配置 spring.pulsar.client.service-url 属性，连接到你自己的 Pulsar 集群。

最关键的是：你需要配置 mq.topics.xxx.topic 属性，才能启用对应的 Listener。

另一方面，如果你还没准备好搭建 Pulsar 服务，也可以选择不配置，或注释掉 mq.topics.xxx 相关 topics，以避免因无法启动而阻塞。

5. 通过 Docker Compose 启动 Minio（可选）


docker-compose -f deploy/minio/docker-compose.yml up -d

Minio API 地址

http://localhost:9000

Minio Web UI 控制台

http://localhost:9001 Username: minioadmin Password: minioadmin

6. 通过 Docker Compose 启动 Demo 应用


docker-compose -f ./deploy/demo-app/docker-compose.yml up -d

无需任何 SQL 种子：空数据库上，启动对账器会先依据 sys_* 目录表自身的注解创建这几张表，随后 ["*"] 范围的扫描器自动创建全部业务表。若需要一份可审阅的参考 DDL（DB-first 工作流、DBA 审查），按需生成：REGEN_BASELINE=true mvn test -pl apps/demo-app -Dtest=MetadataBaselineDdlGenerator。

7. 生产环境

强烈建议生产环境通过流水线，并使用 Kubernetes 进行容器化部署。

7.1 可观测性

Softa 附带的 compose 文件是开发用编排：每个都钉了 json-file 驱动并配了轮转——Docker 的默认行为是不轮转的，本地栈长跑会把磁盘写满。

服务器上则不要按服务钉死驱动。Docker 按驱动校验 option 键名，一个 logging: 块无法同时服务开发机和日志平台；要让它条件化就只能再加一个 overlay 文件，而它必须在每次手工 up 时被记得——忘掉一次，整个栈就静默退回本地日志。改配 /etc/docker/daemon.json：每台主机一处设置，覆盖其上所有容器，没有可忘的东西。任何把日志送出主机的驱动还必须设 mode: non-blocking 并配 max-buffer-size——默认是 blocking，目标端变慢时会阻塞容器的写入，进而拖住应用线程。

应用侧的部分——ECS 结构化 JSON 日志、框架写入 MDC 的 traceId / tenantId / userId 字段、以及经 sentry-starter 的错误追踪与链路追踪——见可观测性，那里也给出了两份 daemon.json 配方。