ArchForge

中文

English

中文

English

Appearance

配置说明 ​

ArchForge 使用 Spring Boot 基于 Profile 的配置系统，自定义属性前缀为 arch-forge。

Profile 体系 ​

Profile文件数据库RedisFlyway验证码
dev（默认）application-dev.yamlTestcontainers PostgreSQLTestcontainers Redis已禁用已禁用
testapplication-test.yamlPostgreSQL真实 Redis已启用已启用
prodapplication-prod.yamlPostgreSQL（主从）真实 Redis已启用已启用

通过环境变量或 JVM 参数切换 Profile：

bash
# Environment variable
SPRING_PROFILES_ACTIVE=prod ./gradlew :archforge-server-admin:bootRun

# JVM argument
java -Dspring.profiles.active=prod -jar archforge-server-admin.jar

配置文件 ​

archforge-archforge-server-admin/src/main/resources/
├── application.yaml              # 共享基础配置（所有 Profile）
├── application-dev.yaml          # 开发环境覆盖配置
├── application-test.yaml.example # 测试环境模板（复制后编辑）
├── application-prod.yaml.example # 生产环境模板（复制后编辑）
└── log4j2-spring.xml            # 日志配置（含 <SpringProfile> 区分）

WARNING

application-test.yaml 和 application-prod.yaml 已被 gitignore。请始终从 .example 文件复制并填入真实配置值。

ArchForge 属性（arch-forge.*） ​

核心设置 ​

yaml
arch-forge:
  name: ArchForge                      # Application name
  version: 1.0.0                      # Version string
  copyright-year: 2025                # Footer copyright year
  captcha-type: math                  # Captcha type: "math" or "text"
  rsa-private-key: "MIICeAIB..."     # RSA key for frontend encryption

Sa-Token 配置 ​

认证使用 Sa-Token，不是 JWT / Spring Security。管理端用 StpAdminUtil，C 端用 StpWebUtil。

yaml
sa-token:
  token-name: Authorization
  token-prefix: Bearer
  timeout: 604800                     # 7 days
  token-style: uuid
  is-read-cookie: false

DANGER

生产环境密钥 没有默认值。必须显式配置 DB_PASSWORD、Redis、RSA 等环境变量。

Token 配置 ​

yaml
arch-forge:
  token:
    header: Authorization             # HTTP header name
    auto-refresh-time: 20             # Auto-refresh threshold (minutes)

验证码配置 ​

yaml
arch-forge:
  captcha:
    enabled: true                     # Enable/disable login captcha

服务器监控 ​

yaml
arch-forge:
  monitor:
    enabled: true                     # Enable Oshi system monitoring

内嵌服务（仅开发环境） ​

yaml
arch-forge:
  embedded:
    redis: true                       # Start Redis via Testcontainers
    postgresql: true                  # Start PostgreSQL via Testcontainers
    rustfs: true                       # Start RustFS (S3) via Testcontainers

数据脱敏 ​

yaml
arch-forge:
  sensitive:
    enabled: true                     # Enable sensitive data masking in responses

数据源配置 ​

ArchForge 使用 dynamic-datasource-spring-boot4-starter 实现多数据源支持和主从路由。

开发环境（Testcontainers PostgreSQL） ​

yaml
spring:
  datasource:
    dynamic:
      primary: user_master
      strict: false
      datasource:
        user_master:
          driver-class-name: org.postgresql.Driver
          url: jdbc:postgresql://${TESTCONTAINERS_PG_HOST}:${TESTCONTAINERS_PG_PORT}/archforge
          username: archforge
          password: archforge
        user_slave:
          driver-class-name: org.postgresql.Driver
          url: jdbc:postgresql://${TESTCONTAINERS_PG_HOST}:${TESTCONTAINERS_PG_PORT}/archforge
          username: archforge
          password: archforge

TIP

在开发模式下，Testcontainers 会自动启动 PostgreSQL 并注入连接属性。无需手动配置这些值。

生产环境（PostgreSQL） ​

yaml
spring:
  datasource:
    dynamic:
      primary: user_master
      strict: false
      datasource:
        user_master:
          driver-class-name: org.postgresql.Driver
          url: jdbc:postgresql://master-host:5432/archforge
          username: ${DB_USERNAME}
          password: ${DB_PASSWORD}
        user_slave:
          driver-class-name: org.postgresql.Driver
          url: jdbc:postgresql://slave-host:5432/archforge
          username: ${DB_USERNAME}
          password: ${DB_PASSWORD}

在 Service 方法中使用 @DS("group_name") 注解进行显式数据源路由。

Flyway 配置 ​

yaml
arch-forge:
  flyway:
    enabled: true    # Enable Flyway migrations (test/prod only)

spring:
  jpa:
    hibernate:
      ddl-auto: validate   # Flyway manages DDL; Hibernate only validates

详见 数据库迁移 获取完整的 Flyway 指南。

文件存储配置 ​

ArchForge 支持文件上传/下载，提供两种后端选项：本地文件系统和 S3 兼容存储（如 RustFS）。

本地存储 ​

yaml
arch-forge:
  file-storage:
    type: local
    local:
      base-path: /data/archforge/uploads    # Directory for stored files

S3 / RustFS 存储 ​

yaml
arch-forge:
  file-storage:
    type: s3
    s3:
      endpoint: http://localhost:9000       # RustFS or S3 endpoint
      access-key: ${MINIO_ACCESS_KEY}
      secret-key: ${MINIO_SECRET_KEY}
      bucket: archforge                      # Default bucket name
      region: us-east-1                     # AWS region (or leave default for RustFS)

TIP

在开发模式下，RustFS 通过 Testcontainers 自动启动。S3 端点和凭据会自动注入——无需手动配置。

日志 ​

日志通过 log4j2-spring.xml 配置，使用 <SpringProfile> 实现不同 Profile 的差异化行为：

  • dev：控制台输出，彩色格式
  • 非 dev：仅文件输出，支持日志轮转

OpenTelemetry ​

yaml
management:
  tracing:
    sampling:
      probability: 1.0          # dev: 100%, prod: 0.1 (10%)
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
    metrics:
      endpoint: http://localhost:4318/v1/metrics

在生产环境中通过 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量覆盖 OTLP 端点。

Actuator 端点 ​

dev（以及默认 profile）把 actuator 放在业务端口上：

yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
端点URL（dev）
存活 / 就绪探针http://localhost:8080/livez、http://localhost:8080/readyz
健康检查http://localhost:8080/actuator/health
指标http://localhost:8080/actuator/metrics
Prometheushttp://localhost:8080/actuator/prometheus

staging 与 prod 把 actuator 挪到独立的管理端口：它不发布到宿主机，也不经过前端 nginx 代理，外部访问不到 /actuator/prometheus；该端口只暴露 health,info,prometheus：

yaml
management:
  server:
    port: ${MANAGEMENT_SERVER_PORT:8089}   # server-web 为 8091
  endpoints:
    web:
      exposure:
        include: health,info,prometheus

编排器探针仍走业务端口上的 /livez 与 /readyz（management.endpoint.health.probes.add-additional-paths）。存活探针只看进程本身，就绪探针额外检查数据库与 Redis。server-web 同理，对应 8081 / 8091。

错误与 CORS ​

  • 500 响应只带通用消息；异常类名与根因（SQL、表名等）只进日志。arch-forge.error.expose-details: true 会把它们放回响应——dev 与 test profile 打开，staging 与 prod 不要打开。
  • 业务错误仍返回 HTTP 200，错误码在 body 的 code 里，并计入 archforge_business_errors_total{code}。
  • 除 dev/test 外的 profile，arch-forge.cors.allowed-origins 必须写明具体来源；为空或为 * 时应用拒绝启动。

请求日志 ​

arch-forge.request-log 每个请求记一行（接口、方法、状态、耗时，开启时附带请求/响应体）：

  • mask-fields 里的是键名片段：键名（忽略大小写、_ 和 -）包含任一片段就脱敏，所以 token 同时覆盖 accessToken 与 refresh_token。
  • staging 与 prod 把 include-request-payload、include-response-payload 设为 false——请求/响应体里有会话 token 和个人信息。
  • 超过 64 KB（或更大的 max-payload-length）的载荷只记录长度。
  • 每行日志都带 [traceId,requestId]，把 traceId 粘到 Jaeger / Grafana 就能打开这次请求的链路。
  • 脱敏是一次线性扫描，写日志出错也不会改变响应。每个请求只记录一次——异常逃出过滤链时由随后的 /error 转发记录最终状态码。
  • 客户端 IP 每个请求只解析一次，只信任 arch-forge.security.trusted-proxies（与限流共用这份名单）转发来的头：在这些代理之后，取 X-Forwarded-For 里代理没有追加的最右一个地址；否则取对端地址。请求日志、操作日志、登录日志和在线用户都用这个值——客户端没法自己决定写进去的 IP。

相关页面 ​


---

Released under the MIT License.

Copyright © 2026-present ArchForge