chore(ci): CI/CD 三阶段 6 job + test/prod 环境 + 启动前的配置自检

.gitlab-ci.yml:契约与实体对账 / 后端编译 / 管理端类型检查与构建 / 学生端 H5 构建 /
接口断言(全套 E2E 打真库)/ 生产环境自检;密钥每次随机生成,顺带证明应用没有偷偷
依赖 dev 默认值。

ProdEnvCheck 是 EnvironmentPostProcessor,跑在任何 bean 之前,拦 6 类「配错了也能启动」;
判「没配」与「配了」要 try { getProperty } catch(F-86)——
getProperty 会解析占位符、失败就抛,只读 PropertySource 又读不到 env 的值。

删掉 Gi 模板残留的 GitHub Pages 工作流(远端是 GitLab、用 pnpm,且它发布的是没有 API 的静态页)。

验证:scripts/e2e-prodguard.py 9/9(三种误配形态都拒绝启动)。
This commit is contained in:
2026-09-30 09:02:57 +08:00
parent 168c76ed0e
commit 6945f194b5
6 changed files with 707 additions and 82 deletions
@@ -0,0 +1,239 @@
package cn.tianbaotong.fill.config;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.env.EnvironmentPostProcessor;
import org.springframework.core.Ordered;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.EnumerablePropertySource;
import org.springframework.core.env.PropertySource;
import java.util.ArrayList;
import java.util.List;
/**
* 生产环境的**启动前自检**(M7-10 生产环境准备)。
*
* <h3>为什么必须是 {@code EnvironmentPostProcessor},而不是 ApplicationRunner</h3>
*
* <p>我先写成了 {@code ApplicationRunner}(跑在容器就绪之后),实测发现**它根本轮不到**:
* 缺 {@code XT_JWT_SECRET} 时,{@code JwtService} 在**构造 bean** 时就炸了,
* 用户看到的是一段 56 行的 Spring 栈,而我最该被看见的那句清单连影子都没有。
*
* <p>所以挪到 {@code EnvironmentPostProcessor}:它跑在**任何 bean 被创建之前**,
* 只依赖 {@code Environment}(配置已经在里面了,只是还没绑定成对象)。
* 代价是不能用 {@code FillProperties} 的访问器,得按 key 读 —— 但那点啰嗦换来的是
* "报错一定是人话"。
*
* <h3>检查的都是"配错了也能启动、而且运行时完全不报错"的配置</h3>
*
* <table border="1">
* <tr><th>配置</th><th>不检查会怎样</th></tr>
* <tr><td>{@code stub-enabled=true}</td>
* <td><b>任何人可以登录任何学生</b>(它本来就是「跳过微信授权」的开关)</td></tr>
* <tr><td>{@code storage.provider=local}</td>
* <td>多副本部署下<b>必然丢文件</b>(学生这次传到 A 实例、下次落到 B)。
* 这不是"性能差一点",是正确性错误,而且丢的时候没有任何报错</td></tr>
* <tr><td>JWT 密钥还是 dev 那把</td>
* <td>任何人都能拿仓库里那把密钥<b>伪造任意用户的 token</b>(含平台运营)</td></tr>
* <tr><td>AES 密钥还是 dev 那把</td>
* <td>证件号是 AES 加密存的 —— 密钥泄露等于<b>全校身份证可解</b></td></tr>
* <tr><td>Swagger 还开着</td>
* <td>把全部接口与字段暴露给公网</td></tr>
* </table>
*
* <h3>为什么是"拒绝启动"而不是"打个 warn"</h3>
*
* <p>warn 会被淹掉(生产日志一天几万行),而这几条里**任何一条为真都意味着系统不该上线**。
* 宁可让它起不来 —— "起不来"是当场就能发现的事故,"带着后门跑了两周"不是。
*/
public class ProdEnvCheck implements EnvironmentPostProcessor, Ordered {
/** dev 用的 JWT 密钥前缀(用来识别"照抄了 dev 配置")。 */
private static final String DEV_JWT_PREFIX = "BC0LUCKD3T4FfgMioHyARkl";
/** dev 用的 AES 密钥前缀,同理。 */
private static final String DEV_AES_PREFIX = "CaJuBbvbSKkLGn+d3WfWcmbk";
/** 生产必需的键(缺失就报出来,一个都不许少)。 */
private static final String[][] REQUIRED = {
{"XT_JWT_SECRET", "fill.jwt.secret", "HS512 签名密钥,≥ 64 字节随机值"},
{"XT_AES_KEY", "fill.crypto.aes-key", "证件号 AES 加密密钥(base64,32 字节)"},
{"XT_HMAC_KEY", "fill.crypto.hmac-key", "开放接口 HMAC 签名密钥"},
{"XT_RSA_PRIVATE_KEY", "fill.rsa.private-key", "登录密码解密用的 PKCS#8 私钥"},
{"PG_PASSWORD", "spring.datasource.password", "数据库密码"},
{"REDIS_PASSWORD", "spring.data.redis.password", "Redis 密码"},
};
@Override
public int getOrder() {
// 尽量靠前:别的 EnvironmentPostProcessor 不该先跑一半
return Ordered.HIGHEST_PRECEDENCE + 10;
}
@Override
public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
if (!isProd(env)) {
return;
}
List<String> problems = new ArrayList<>();
// ① 必需项:缺一个都别启动
for (String[] r : REQUIRED) {
String v = safe(env, r[1]);
if (isBlank(v) || looksLikeUnresolvedPlaceholder(v)) {
problems.add(r[0] + "(" + r[1] + ")未设置或为空 —— " + r[2]);
}
}
// ② JWT 密钥:不能是 dev 那把,也不能太短
//
// ⚠️ 先排除"未解析的占位符":`${XT_JWT_SECRET}` 正好 16 个字符,
// 不排除的话会对同一个问题报两条,而其中一条("太短")是**错的** ——
// 那会让看日志的人开始怀疑这份清单本身(而它正是用来建立信任的)。
String jwt = safe(env, "fill.jwt.secret");
if (!isBlank(jwt) && !looksLikeUnresolvedPlaceholder(jwt)) {
if (jwt.startsWith(DEV_JWT_PREFIX)) {
problems.add("fill.jwt.secret 用的还是**开发环境那把**(仓库里能查到)—— "
+ "任何人都能拿它伪造任意用户的 token,包括平台运营");
} else if (jwt.length() < 32) {
problems.add("fill.jwt.secret 太短(" + jwt.length() + " 字符)—— "
+ "HS512 至少 32,建议 64 以上");
}
}
// ③ 加密密钥:证件号加密与开放接口签名都用它
String aes = safe(env, "fill.crypto.aes-key");
if (!isBlank(aes) && !looksLikeUnresolvedPlaceholder(aes)) {
if (aes.startsWith(DEV_AES_PREFIX)) {
problems.add("fill.crypto.aes-key 用的还是**开发环境那把** —— "
+ "它用于证件号加密,泄露等于全校身份证可解");
}
// ⚠️ 长度也要查:AES-256 要求 32 字节,而不对的长度会在
// `AesGcmCipher` 构造时抛 IllegalArgumentException ——
// 错误信息本身很清楚,但它出现在**一个 85 层的栈中间**。
// 这里提前说,运维看到的就是人话。
byte[] aesBytes = tryBase64(aes);
if (aesBytes != null && aesBytes.length != 32) {
problems.add("fill.crypto.aes-key 解出来是 " + aesBytes.length
+ " 字节,AES-256 需要 32 字节 —— 用 `openssl rand -base64 32` 生成");
}
}
// ④ stub 登录:开了它就是"任何人可登录任何学生"
if (isTrue(safe(env, "fill.mp-h5.stub-enabled"))) {
problems.add("fill.mp-h5.stub-enabled=true —— 这是「跳过微信授权直接登录」的后门,"
+ "开了它任何人可以登录任何学生。生产必须 false");
}
// ⑤ 存储:local 在多副本下必然丢文件
String provider = safe(env, "fill.storage.provider");
if (isBlank(provider) || "local".equalsIgnoreCase(provider)) {
problems.add("fill.storage.provider=" + provider + " —— 本地磁盘存储在多副本部署下"
+ "**必然丢文件**(学生这次传到 A 实例、下次请求落到 B)。"
+ "生产必须 provider=qiniu 并提供 AK/SK");
} else if ("qiniu".equalsIgnoreCase(provider)) {
if (isBlank(safe(env, "fill.storage.qiniu.access-key"))
|| isBlank(safe(env, "fill.storage.qiniu.secret-key"))) {
problems.add("fill.storage.provider=qiniu 但没有提供 QINIU_ACCESS_KEY / "
+ "QINIU_SECRET_KEY");
}
}
// ⑥ Swagger:生产应当关掉
if (isTrue(safe(env, "springdoc.api-docs.enabled"))) {
problems.add("springdoc.api-docs.enabled 仍然开着 —— 生产会把全部接口与字段"
+ "暴露给公网。要么设 false,要么只在运维网段可达");
}
if (!problems.isEmpty()) {
throw new IllegalStateException(buildMessage(problems));
}
}
/** 拼那句最该被人看见的话。 */
static String buildMessage(List<String> problems) {
return "\n"
+ "══════════════════════════════════════════════════════════════\n"
+ " 生产环境启动自检未通过(" + problems.size() + " 项)\n"
+ "══════════════════════════════════════════════════════════════\n - "
+ String.join("\n - ", problems)
+ "\n\n"
+ "这些配置**配错了也能启动、而且运行时完全不报错** ——\n"
+ "所以这里直接拒绝启动。请核对环境变量后重启。\n"
+ "必需的变量清单见 application-prod.yml 的头部注释,\n"
+ "密钥的生成与轮换见 docs/09-部署与运维.md。\n"
+ "══════════════════════════════════════════════════════════════";
}
private static boolean isProd(ConfigurableEnvironment env) {
for (String p : env.getActiveProfiles()) {
if ("prod".equalsIgnoreCase(p)) {
return true;
}
}
return false;
}
private static boolean isBlank(String s) {
return s == null || s.isBlank();
}
/** `${XT_JWT_SECRET}` 这种"占位符没被解析"的值,等于没配。 */
private static boolean looksLikeUnresolvedPlaceholder(String s) {
return s.startsWith("${") && s.endsWith("}");
}
/**
* **安全地**读一个配置值(这是唯一正确的读法,前两版都错过)。
*
* <p>为什么要包一层 try/catch:
* <ul>
* <li>{@code env.getProperty(key)} 会**解析占位符**,而 prod 配置里写的是
* {@code secret: ${XT_JWT_SECRET}} —— 环境变量没设时它抛
* {@code PlaceholderResolutionException}。于是**"检查缺了什么"的自检
* 自己先崩在"缺了什么"上**,精心写的清单一个字都打不出来;</li>
* <li>只读 {@code PropertySource.getProperty(key)}(完全不解析)也不行:
* 读到的永远是字面量 {@code ${XT_JWT_SECRET}},于是**env 明明设了值
* 也报"未设置"**。这个错更隐蔽 —— 场景"真没设"看起来完全正确,
* 只有"设了值"的场景才暴露。</li>
* </ul>
*
* <p>所以正确做法是**安全解析**:解析成功就用解析后的值,解析失败当没配。
*
* <p>一般化的教训:**做配置检查的代码必须能区分"没配"与"配了"** ——
* 而且它必须比被检查的配置更皮实,否则会在配置最坏的时候自己先炸。
*/
static String safe(ConfigurableEnvironment env, String key) {
try {
return env.getProperty(key);
} catch (RuntimeException e) {
// 占位符解析不出来 = 没配(这正是我们要报的那件事)
return null;
}
}
/** 试解 base64;解不开返回 null(**不抛** —— 检查代码自己不抛异常)。 */
private static byte[] tryBase64(String s) {
try {
return java.util.Base64.getDecoder().decode(s.trim());
} catch (RuntimeException e) {
return null;
}
}
/** 宽松判真(`true` / `TRUE` / `1` 都算)。 */
private static boolean isTrue(String s) {
return s != null && ("true".equalsIgnoreCase(s.trim()) || "1".equals(s.trim()));
}
/** 打印所有属性来源(排障用:确认某个值到底从哪来的)。 */
static List<String> sourcesOf(ConfigurableEnvironment env, String key) {
List<String> out = new ArrayList<>();
for (PropertySource<?> ps : env.getPropertySources()) {
if (ps instanceof EnumerablePropertySource<?> e && e.containsProperty(key)) {
out.add(ps.getName());
}
}
return out;
}
}
@@ -0,0 +1,12 @@
# Spring Boot 的 EnvironmentPostProcessor 注册(META-INF/spring.factories)。
#
# ⚠️ 为什么在 spring.factories 而不是 .../AutoConfiguration.imports:
# `.imports` 是给**自动配置类**用的(它们跑在环境准备好之后);
# 而 EnvironmentPostProcessor 要求**在环境准备的过程中**被加载 ——
# 这个时机只有 spring.factories 能表达。
#
# ⚠️ 注册错的表现是"检查静默不生效":应用照常启动、没有任何报错,
# 而你以为生产自检在起作用。所以 scripts/e2e-prodguard.py 会**真的起一次**
# 来验证它被调用了(不是只看代码在不在)。
org.springframework.boot.env.EnvironmentPostProcessor=\
cn.tianbaotong.fill.config.ProdEnvCheck
@@ -0,0 +1,147 @@
# ═══════════════════════════════════════════════════════════
# 生产环境(prod)
#
# ⚠️⚠️ 这个文件里**一个密钥都没有,也永远不要加**。
# 全部由环境变量提供;缺失时 **ProdGuard 会拒绝启动**
# (见 config/ProdGuard.java —— 那 6 条都是"配错了也能启动、
# 而且运行时完全不报错"的配置)。
#
# ── 必需的环境变量 ──────────────────────────────────────
# 数据库 PG_HOST PG_PORT PG_DB PG_USER PG_PASSWORD
# 缓存 REDIS_HOST REDIS_PORT REDIS_PASSWORD
# 密钥 XT_JWT_SECRET HS512,≥ 64 字节随机值
# XT_AES_KEY AES-256,base64,**用于证件号加密**
# XT_HMAC_KEY HMAC,用于开放接口签名
# XT_RSA_PRIVATE_KEY PKCS#8 单行 base64(登录密码解密)
# 存储 XT_STORAGE_PROVIDER=qiniu
# QINIU_ACCESS_KEY QINIU_SECRET_KEY QINIU_BUCKET QINIU_DOMAIN
# 微信 WX_MP_APP_ID WX_MP_APP_SECRET (小程序)
# WX_H5_APP_ID WX_H5_APP_SECRET (公众号网页授权)
# WX_H5_CALLBACK WX_H5_BASE_URL (必须是 https 正式域名)
# 其他 H5_STATIC_DIR(H5 构建产物目录)
#
# ⚠️ 密钥怎么生成、怎么轮换、轮换时要注意什么,见
# docs/09-部署与运维.md §3「密钥与凭据」。
# ═══════════════════════════════════════════════════════════
spring:
datasource:
url: jdbc:postgresql://${PG_HOST}:${PG_PORT:5432}/${PG_DB:filldb}?stringtype=unspecified
username: ${PG_USER}
password: ${PG_PASSWORD}
hikari:
# 生产把池子放大一些:导出打包是长事务,会占住连接
minimum-idle: 10
maximum-pool-size: 40
data:
redis:
host: ${REDIS_HOST}
port: ${REDIS_PORT:6379}
password: ${REDIS_PASSWORD}
database: 0
flyway:
# ⚠️⚠️ 生产**禁止 clean**。它是"清空整个库再重建",
# 在生产上执行等于把所有学校的填报数据删掉。
# 流水线里也不要用 flyway clean —— 见部署文档的回滚一节。
clean-disabled: true
# 迁移文件发布后不许改(改了校验失败)。这是保护:它保证
# "生产跑的迁移"与"仓库里的迁移"逐字节一致
validate-on-migrate: true
web:
resources:
# H5 产物由部署流程放到这个目录(**不进仓库**)
static-locations: ${H5_STATIC_DIR:file:/opt/xt/h5/},classpath:/static/
server:
# 生产在反向代理后面:让 Spring 认 X-Forwarded-* ,
# 否则生成的回调地址会是 http://内网IP:8080
forward-headers-strategy: framework
tomcat:
# 上传是长连接,生产放宽(学生可能从聊天记录里选一个 40MB 的文件)
connection-timeout: 120s
threads:
max: 200
min-spare: 20
logging:
level:
root: warn
cn.tianbaotong.fill: info
file:
# ⚠️ 日志按天滚动并保留 30 天:审计要能回答"上周三谁看过那份证件号"
name: ${XT_LOG_DIR:/var/log/xt}/xt-server.log
logback:
rollingpolicy:
max-history: 30
max-file-size: 200MB
total-size-cap: 20GB
# 生产关掉接口文档:它会把全部接口与字段暴露给公网。
# ProdGuard 会检查这一条 —— 开着就拒绝启动。
springdoc:
api-docs:
enabled: false
swagger-ui:
enabled: false
management:
endpoints:
web:
exposure:
# 生产只暴露健康检查(给负载均衡探活)
include: health
endpoint:
health:
show-details: never
fill:
jwt:
secret: ${XT_JWT_SECRET}
crypto:
aes-key: ${XT_AES_KEY}
hmac-key: ${XT_HMAC_KEY}
rsa:
private-key: ${XT_RSA_PRIVATE_KEY}
security:
login-max-fail: 5
login-lock-minutes: 15
captcha-after-fails: 2
storage:
# 生产必须 qiniu(local 在多副本下必然丢文件,ProdGuard 会拦)
provider: qiniu
prefix: xiaotutongxue
keep-raw: ${XT_STORAGE_KEEP_RAW:false}
self-check-on-startup: ${XT_STORAGE_SELF_CHECK:true}
qiniu:
access-key: ${QINIU_ACCESS_KEY}
secret-key: ${QINIU_SECRET_KEY}
bucket: ${QINIU_BUCKET}
domain: ${QINIU_DOMAIN}
region: ${QINIU_REGION:auto}
signed-url-expire-seconds: 1800
mini-program:
app-id: ${WX_MP_APP_ID}
app-secret: ${WX_MP_APP_SECRET}
# ⚠️ 正式发布后用 release。用 trial/develop 生成的码扫开会提示
# 「小程序未发布」,而**接口不报错** —— 只会让人以为码生成得不对
env-version: ${WX_MP_ENV_VERSION:release}
page: pages/index/index
public-base-url: ${WX_MP_PUBLIC_BASE_URL}
code-cache-days: 30
mp-h5:
app-id: ${WX_H5_APP_ID}
app-secret: ${WX_H5_APP_SECRET}
callback-url: ${WX_H5_CALLBACK}
h5-base-url: ${WX_H5_BASE_URL}
# ⚠️⚠️ 生产**必须** false。开了它就是"任何人可登录任何学生"。
# 这是 ProdGuard 的第一条检查,写成 true 直接拒绝启动。
stub-enabled: false
tenant-domain:
enabled: ${XT_TENANT_DOMAIN_ENABLED:false}
base: ${XT_TENANT_DOMAIN_BASE:}
scheme: https
@@ -0,0 +1,87 @@
# ═══════════════════════════════════════════════════════════
# 测试环境(test)
#
# 用途:CI 流水线里的 E2E(`scripts/e2e-*.py` 打真实接口)与联调环境。
#
# ⚠️⚠️ 这个文件**不含任何密钥**,全部由环境变量提供。
# 理由不是"洁癖":test 环境的库会被反复清空重建,
# 而**密钥不该跟着库一起被当成一次性的**。更实际的是 ——
# CI 上每次跑用**当次随机生成**的密钥(见 .gitlab-ci.yml),
# 这样才能证明"应用没有偷偷依赖某个 dev 默认值"。
#
# 必需的环境变量(缺任何一个都起不来,且报错会指名道姓):
# PG_HOST PG_PORT PG_DB PG_USER PG_PASSWORD
# REDIS_HOST REDIS_PORT REDIS_PASSWORD
# XT_JWT_SECRET XT_AES_KEY XT_HMAC_KEY XT_RSA_PRIVATE_KEY
# ═══════════════════════════════════════════════════════════
spring:
datasource:
# CI 里 PG 是 services 里的别名(默认 `postgres`),本地跑给 localhost 即可
url: jdbc:postgresql://${PG_HOST:localhost}:${PG_PORT:5432}/${PG_DB:filldb}?stringtype=unspecified
username: ${PG_USER:fill}
password: ${PG_PASSWORD}
data:
redis:
host: ${REDIS_HOST:localhost}
port: ${REDIS_PORT:6379}
password: ${REDIS_PASSWORD}
database: 0
flyway:
# test 允许 clean 后重建:每次流水线从一个空库开始,
# **这样才能验证"所有迁移从 V1 依次跑到最新"是通的** ——
# 而增量环境里永远验不到这件事(旧库已经是最新了)
clean-disabled: false
web:
resources:
# H5 产物在 CI 里是构建出来的;本地指向同一个相对路径
static-locations: ${H5_STATIC_DIR:file:../frontend-mp/dist/build/h5/},classpath:/static/
logging:
level:
root: info
cn.tianbaotong.fill: info
# CI 日志里带 SQL 会淹没断言输出,所以 test 不打开 SQL 日志
fill:
jwt:
secret: ${XT_JWT_SECRET}
crypto:
aes-key: ${XT_AES_KEY}
hmac-key: ${XT_HMAC_KEY}
rsa:
private-key: ${XT_RSA_PRIVATE_KEY}
storage:
# ⚠️ test 用 local 是**刻意的**:CI 里没有对象存储,而且
# "上传→取回→预览"这条链路用本地磁盘就能完整验证。
# 真实验证七牛要走 staging(那需要真凭据),见 docs/09-部署与运维.md
provider: ${XT_STORAGE_PROVIDER:local}
keep-raw: ${XT_STORAGE_KEEP_RAW:false}
self-check-on-startup: false
mini-program:
app-id: ${WX_MP_APP_ID:}
app-secret: ${WX_MP_APP_SECRET:}
env-version: develop
mp-h5:
app-id: ${WX_H5_APP_ID:}
app-secret: ${WX_H5_APP_SECRET:}
callback-url: ${WX_H5_CALLBACK:http://localhost:8080/api/v1/mp/h5/callback}
h5-base-url: ${WX_H5_BASE_URL:http://localhost:8080}
# ⚠️ test 允许打桩登录(E2E 里有 23 条断言靠它跑 H5 授权链路)。
# 它只在**非生产**可用:代码里另有一道"profile 不含 prod"的判断。
stub-enabled: ${WX_H5_STUB:true}
tenant-domain:
enabled: ${XT_TENANT_DOMAIN_ENABLED:false}
base: ${XT_TENANT_DOMAIN_BASE:localhost}
scheme: http
# test 也开 Swagger:联调的人要用它照着调
springdoc:
api-docs:
enabled: true
swagger-ui:
enabled: true