跳到主要内容

Docker

本页描述的所有文件都由 mars create 生成到你的项目里 —— 项目根目录的 compose 文件,以及各个 apps/<platform>/ 内的 Dockerfile。你可以用 mars dev --docker / mars build --docker 驱动它们,也可以直接用 docker compose。

先复制环境变量模板。一共两份,区别只在镜像构建时从哪里下载 npm 包与 Maven 依赖:

cp .env.example .env # 官方源(默认)
cp .env.example.cn .env # 国内镜像源

复制完再改 MYSQL_* / REDIS_* / NGINX_HOST_PORT。两份模板声明的键和值完全一致, 只有 NPM_REGISTRY 和 MAVEN_MIRROR_URL 不同,所以之后想换源,改两行就够,不用重新 复制。改完任意一份之后跑 pnpm check:env,两份一旦不一致它会以非零退出码报错。

.env 里还有一个 COMPOSE_PROJECT_NAME,mars create 会把它改写成你的项目名。 它的作用是固定 compose 的项目名,而不是让 compose 默认取小写的目录名——这样换个 目录名检出,就不会悄悄变成另一个项目。它只能放在环境变量里,不能写进 YAML: compose v2.0.0 会直接拒绝顶层的 name: 字段,报 (root) Additional property name is not allowed。项目名必须是小写。

两个 compose 文件​

它们的唯一区别在于镜像是否自己编译源码:

# 全新检出 / 没有本地工具链:在镜像内部编译
docker compose -f docker-compose.build.yml up -d

# 产物已编译好(jar + dist 存在):只做打包,几秒完成
docker compose up -d

两个文件都是完整且可用单个 -f 独立运行的,因此 VS Code 的 Docker 插件可以直接 点击运行任意一个。它们都把 MySQL 与 Redis 当作外部服务,通过 host.docker.internal 访问。

服务镜像主机端口(对外发布)
apimarsquakes/api:3.9.3仅内网(8817)
web-adminmarsquakes/web-admin:3.9.3仅内网(80)
nginxnginx:stable-alpine${NGINX_HOST_PORT:-80}:80

nginx 是边缘反向代理,也是唯一对外发布的服务:/ 转发到 web-admin 容器,/marsquakes-api/ 转发到 API(重写为 /marsquakes-api 上下文路径),并处理 WebSocket 升级。它的配置是 apps/web-admin/edge-nginx.conf,以只读方式挂载进 官方镜像,无需自建镜像。只有当主机 80 端口被占用时才需要改 NGINX_HOST_PORT; 内网端口始终不变。

docker-compose.build.yml 通过服务级的 extends 继承 docker-compose.yml, 只覆盖 build.dockerfile 一项。

注意

extends 继承的是服务而不是项目 —— 顶层 networks: 不会被继承。 被继承服务引用的每个网络都必须在覆盖文件中重新声明,否则 compose 会直接报 service "api" refers to undefined network <net>。而 depends_on 与 container_name 会被继承,不要重复声明。

基础服务​

docker-compose.infra.yml 在本地提供 MySQL 与 Redis,让一次全新检出无需在宿主机 安装数据库就能完整跑起来。它是用 -f 叠加的独立文件,而不是 extends 覆盖: 叠加是在项目层面合并的,因此同一个文件可以与任意一个应用栈组合。

# 只起基础服务 —— 应用仍从 IDE 里跑,连这两个容器
docker compose -f docker-compose.infra.yml up -d

# 与应用栈一起启动
docker compose -f docker-compose.yml -f docker-compose.infra.yml up -d
docker compose -f docker-compose.build.yml -f docker-compose.infra.yml up -d
服务镜像端口
mysqlmarsquakes/mysql:8.0.36${MYSQL_HOST_PORT:-3306}:3306
redisredis:7-alpine${REDIS_HOST_PORT:-6379}:6379

宿主机端口用的就是标准的 3306 与 6379,现有连接串和 IDE 数据源都不用改。如果宿主机上 本来就跑着自己的 MySQL / Redis,请在 .env 里覆盖 MYSQL_HOST_PORT / REDIS_HOST_PORT,不要去改 compose 文件。另外别指望端口冲突一定会报错:Linux 上绑定 会直接失败,但 Windows 上的 Docker Desktop 可能照样绑定成功,此时客户端会不声不响地 继续连到宿主机上那个实例,而不是容器。网络内部端口始终是 3306 与 6379。

注意

叠加使用时必须在 .env 里设置 MYSQL_HOST=mysql 与 REDIS_HOST=redis。 默认值指向 host.docker.internal,不改的话 api 会绕开你刚刚启动的容器 —— 这种故障看起来像连接问题,实际上是配置问题。.env.example 里已经准备好这段 注释掉的配置,取消注释即可。

MySQL 镜像由 apps/api/db/Dockerfile 构建,把 JeecgBoot 的表结构内置到 /docker-entrypoint-initdb.d。这些脚本只执行一次,按文件名顺序,且仅在数据目录 为空时执行 —— 想重新导入必须用 docker compose down -v 删掉卷。有三个服务端参数 是关键的:--lower_case_table_names=1(Linux 区分大小写,而 mapper 假设不区分)、 --max_allowed_packet=128M(默认 4M 会让约一万行的 dump 中途失败)以及 --character-set-server=utf8mb4。

警告

基础镜像固定的是 补丁版本 mysql:8.0.36,不是浮动的 mysql:8.0,请不要"顺手"改回去。 mysql 官方镜像基于 Oracle Linux,而 OL 9 的 glibc 是 2.34,会触发 AGENTS.md 里记录的 clone3 seccomp 限制:在 Docker 20.10.8 上,mysql:8.0(当前 8.0.46 / OL 9.7)会在 --initialize 阶段就以 Can't create thread to handle bootstrap (errno: 1) 失败, 之后无限重启并抱怨数据目录非空,把真正的首个错误埋在日志深处。8.0.36(OL 8.9 / glibc 2.28) 实测正常。升级这个固定版本前先确认新标签的 glibc: docker run --rm --entrypoint sh mysql:<tag> -c "ldd --version | head -1"。

表结构文件名里的 5.7 指的是 Navicat 导出时的 源库 版本,不是运行要求:dump 中所有 标识符都用反引号包裹(8.0 新增的 rank / groups / over 等保留字不会出问题),也没有 NO_AUTO_CREATE_USER、GRANT ... IDENTIFIED BY、零日期或 MyISAM。MySQL 5.7 已于 2023 年 10 月停止维护,不要为了迁就文件名去降级服务端。

api 无法对另一个文件里的服务声明 depends_on,因此它会在表结构导入完成前就启动 并退出;restart: on-failure 会不断把它拉起来直到数据库可用。首次 up 时出现几次 重启属于预期行为。

Dockerfile 变体​

Dockerfile 与它所构建的代码放在一起,位于各平台目录内。变体名称按 镜像是否编译源码 命名,而不是按 CLI 动词命名。

文件是否编译源码用途
<platform>/Dockerfile否打包已构建产物;产物不存在则直接失败
<platform>/Dockerfile.build是自包含的多阶段构建
<platform>/Dockerfile.dev否开发镜像,挂载源码、支持热更新

mars CLI 的 --docker 参数会从 platforms.json 解析平台目录, 按模式挑选变体(dev → Dockerfile.dev,build → Dockerfile.build, 各自在缺失时回退到裸 Dockerfile),然后构建并运行容器。

构建上下文​

构建上下文始终是仓库根目录,因此所有 COPY 都使用相对仓库根的路径 (例如 COPY apps/api/pom.xml ./)。正因如此,Dockerfile 才能访问 pnpm-workspace.yaml、turbo.json 与 packages/* 这类 workspace 级文件。

根目录的 .dockerignore 决定发送给 daemon 的内容。它排除了 **/target 与 **/dist,所以裸 Dockerfile 需要用到的任何产物路径,都必须用 ! 规则 显式重新包含,且该规则必须放在这些排除项之后。

基础镜像约束​

有两条约束是关键性的,都已在真实机器上复现过 —— 请不要“顺手清理”掉。

1. 把镜像标签锁定在 glibc 2.31(-focal / -bullseye)​

Docker 20.10.8 的默认 seccomp 配置没有放行 clone3 系统调用。基于 glibc >= 2.34 构建的镜像(jammy、trixie —— 也就是 node 的默认标签 —— 以及 amazoncorretto)创建线程时会以 EPERM 失败。JVM 会把它误报为 insufficient memory ... Cannot create worker GC thread,让你去排查一个 根本不存在的内存问题。

已验证可用:maven:3.9-eclipse-temurin-17-focal、eclipse-temurin:17-jre-focal、 node:22-bullseye-slim、nginx:stable,以及任意 alpine 标签。 --security-opt seccomp=unconfined 也能绕过;升级 Docker 到 23+ 可彻底消除该约束。

2. apps/web-admin 必须保留 css.preprocessorMaxWorkers: 0​

Vite 7 的 preprocessorMaxWorkers 默认为 true,会启动 availableParallelism() - 1 个 less worker 线程。每个 worker 的 waitUnlock() 使用 Atomics.wait(..., 5000),其超时时间是硬编码的 5 秒,一旦超时就抛出 Error("timed-out")。在容器里主线程的卡顿足以触发它,于是 vite build 每次都在不同的 .less 文件上失败 —— 这让它看起来像源码 bug 而不是超时。 设为 0 则在主进程内执行 less:更慢,但结果确定。

提示

vite-plugin-pwa 的 buildEnd 钩子会吞掉真正的错误信息,只在构建日志里留下一个 空错误。想看到真实原因,可以构建一个停在 build 步骤之前的镜像,进去手动执行 pnpm exec vite build --mode docker。

域名解析与 HTTPS​

由于边缘 nginx 是唯一对外发布的服务,域名只需解析到运行该容器的主机公网 IP 即可;api 与 web-admin 始终不对公网暴露。下文示例统一使用 admin.example.com,请替换成你自己的域名。

还没有服务器或域名,或者不确定下面该填哪个 IP?见服务器与域名准备附录。

域名解析(阿里云云解析 DNS)​

  1. 域名在阿里云注册时会自动开通云解析 DNS。如果域名在其他注册商处,先在 阿里云 云解析 DNS 控制台添加域名,再到原注册商把 NS 修改为阿里云 分配的 DNS 服务器,完成解析托管。
  2. 进入该域名的解析设置,添加指向本套服务的记录:
记录类型记录值
admin.example.comA运行边缘 nginx 的主机公网 IP
api.example.com(可选)A同一公网 IP(已有 /marsquakes-api/ 前缀,无需单独域名)
  1. 等待解析生效(默认记录 TTL 通常为 10 分钟),然后验证:
dig +short admin.example.com
nslookup admin.example.com
注意

服务器位于中国大陆时,域名必须先完成 ICP 备案,否则云解析会拦截、 网站无法通过 80/443 端口对外访问。备案主体需与云服务器(如阿里云 ECS) 对应,备案通过通常需要若干个工作日。服务器位于中国香港或海外则无需备案。

HTTPS 证书​

有两条证书路径,区别在于 TLS 在哪一层终结,以及使用阿里云数字证书管理 服务的哪一种证书。

个人测试证书部署到 SLB / CDN(终结在 SLB / CDN)。 在阿里云数字证书 管理服务申请免费的个人测试证书(DV,有效期 90 天),通过 DNS 自动验证后, 把证书部署到 SLB 监听或 CDN。由 SLB / CDN 负责 HTTPS 卸载,再以 HTTP 回源到边缘 nginx,nginx 现有配置无需改动。

证书下载后终结在边缘 nginx。 当客户端直接访问 nginx 容器时,在阿里云 数字证书管理服务申请证书(免费的个人测试证书有效期 90 天,付费正式证书 有效期 1 年),下载时选择 Nginx 类型,得到 PEM 格式的证书链和私钥。 把这两个文件放入宿主机上固定的、已被 git 忽略的目录 apps/web-admin/certs/, 分别命名为 fullchain.pem(证书链)和 privkey.pem(未加密私钥)。

通过覆盖 nginx 服务发布 443 端口并挂载该目录(项目层面合并,原 compose 文件不用改):

# docker-compose.override.yml
services:
nginx:
ports:
- '80:80'
- '443:443'
volumes:
- ./apps/web-admin/edge-nginx.ssl.conf:/etc/nginx/conf.d/default.conf:ro
- ./apps/web-admin/certs:/etc/nginx/certs:ro

该目录在容器内挂载为 /etc/nginx/certs,nginx 只读取其中的 fullchain.pem 和 privkey.pem 两个文件。

完整的 TLS server 配置——同样的 / 和 /marsquakes-api/ 路由,加上 HTTP 到 HTTPS 的跳转和 ssl_certificate 行——已在仓库中提供: apps/web-admin/edge-nginx.ssl.conf.example。把它复制为 apps/web-admin/edge-nginx.ssl.conf,将 admin.example.com 替换成你的 域名,再按上面挂载即可。

校验并重载,再检查线上证书:

docker compose exec nginx nginx -t
docker compose exec nginx nginx -s reload
curl -I https://admin.example.com

个人测试证书 90 天到期(付费正式证书 1 年到期),请在到期前重新申请、下载 Nginx 类型证书并替换 apps/web-admin/certs/ 中的同名文件,然后 reload nginx。

代理:在中国大陆拉取 Docker Hub​

本仓库所有 Dockerfile 都使用 Docker Hub 官方镜像。在中国大陆直连 docker.io / registry-1.docker.io 通常会被 DNS 污染或连接超时,docker pull 常见报错包括:

  • dial tcp: lookup registry-1.docker.io: no such host
  • net/http: TLS handshake timeout
  • 一直卡在 Pulling fs layer 没有进度

解决办法是给 Docker daemon 配置 HTTP/HTTPS 代理,而不是替换成第三方镜像源: 第三方镜像源可用性不稳定,而本仓库锁定的 glibc 版本与镜像结构只在官方镜像上验证过 (见上方的基础镜像约束)。

Docker Desktop(Windows / macOS)​

打开 Settings → Resources → Proxies,选择 Manual proxy configuration, 填入本机代理客户端的地址(例如 Clash 默认的 http://127.0.0.1:7890,以你的客户端 实际端口为准):

  • HTTP Proxy:http://127.0.0.1:7890
  • HTTPS Proxy:http://127.0.0.1:7890
  • No proxy:localhost,127.0.0.1,host.docker.internal

点击 Apply & Restart,等 daemon 重启完成即可。

Linux(systemd)​

Linux 上 Docker daemon 由 systemd 管理,需要通过 drop-in 文件给 daemon 服务 注入代理环境变量:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

把 127.0.0.1:7890 换成你代理客户端实际监听的地址与端口。

验证是否生效​

docker info | grep -A 3 'HTTP Proxy'
docker pull hello-world

docker info 能看到代理地址、hello-world 能拉取成功,说明 daemon 的网络已经 走代理。

构建镜像时的网络​

docker build 阶段容器内部访问网络使用的是另一套配置。Docker 23+ 会自动读取 ~/.docker/config.json 中的 proxies 段并注入构建参数:

{
"proxies": {
"default": {
"httpProxy": "http://127.0.0.1:7890",
"httpsProxy": "http://127.0.0.1:7890",
"noProxy": "localhost,127.0.0.1"
}
}
}

镜像构建过程中的 npm / Maven 包下载不需要走代理:使用 .env.example.cn 模板(NPM_REGISTRY 指向 npmmirror、MAVEN_MIRROR_URL 指向阿里云 Maven) 即可让这部分下载走国内源。代理只用于拉取 Docker Hub 基础镜像。