部署

StackRivet 部署为单个后端 jar 加一个静态管理端包。Flyway 在启动时自动迁移数据库，所以一次部署就是：构建、配环境、运行。

构建产物

# 后端 fat jar
cd stackrivet-server
./mvnw -pl stackrivet-app -am package -DskipTests     # → stackrivet-app/target/stackrivet-app.jar

# 静态管理端包
cd ../stackrivet-admin-ui
pnpm install && pnpm build                          # → dist/

运行后端

从环境加载配置，再运行 jar：

cd stackrivet-server
set -a && source .env && set +a    # datasource、STACKRIVET_REDIS_*、JWT secret、存储凭据
export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # JDK 21
java -jar stackrivet-app/target/stackrivet-app.jar

应用在 :8080 启动 Tomcat 并运行 Flyway；启动耗时取决于机器和数据库。确认：

curl http://127.0.0.1:9090/actuator/health   # {"status":"UP"}

把管理端 dist/ 作为静态文件托管（如放在 Nginx 后），并把 /api/* 代理到应用端口。若需要暴露 /actuator/*，应走管理端口并放在运维网络内。

最小生产形态 .env：

STACKRIVET_PROFILE=prod
STACKRIVET_PORT=8080
STACKRIVET_MANAGEMENT_PORT=9090
STACKRIVET_MANAGEMENT_ADDRESS=127.0.0.1
STACKRIVET_DB_VENDOR=mysql
SPRING_DATASOURCE_URL=jdbc:mysql://db.example.com:3306/stackrivet?serverTimezone=UTC&useUnicode=true&characterEncoding=utf8&sslMode=VERIFY_CA
SPRING_DATASOURCE_USERNAME=stackrivet
SPRING_DATASOURCE_PASSWORD=change-me
STACKRIVET_REDIS_HOST=redis.example.com
STACKRIVET_REDIS_PASSWORD=change-me
STACKRIVET_SECURITY_JWT_SECRET=replace-with-at-least-32-random-bytes
STACKRIVET_STORAGE_TYPE=s3
STACKRIVET_S3_ENDPOINT=https://s3.example.com
STACKRIVET_S3_BUCKET=stackrivet
STACKRIVET_S3_ACCESS_KEY=change-me
STACKRIVET_S3_SECRET_KEY=change-me

最小 Nginx 结构：

server {
  listen 443 ssl http2;
  server_name stackrivet.example.com;
  root /srv/stackrivet-admin-ui/dist;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

拓扑

形态	布局
本地开发	Vite dev server + Spring Boot + Docker MySQL/PostgreSQL + MinIO
小团队生产	Nginx → 静态管理端 + Spring Boot 应用 → 托管 MySQL/PostgreSQL → S3 / OSS
企业	负载均衡 → 多个应用节点 → HA 数据库 + 企业对象存储 + OIDC/SAML/LDAP

请求处理按可横向扩展设计——上传路径服从当前存储能力、重任务走异步任务、列表分页——因此可在负载均衡后增加节点。本地与 OSS 上传经应用节点中转；S3 可声明绑定字节数的直传与分片路径。

生产必做项

• 对象存储，不是本地磁盘。 把 STACKRIVET_STORAGE_TYPE 设为 s3 或 aliyun_oss（见配置对象存储）；本地文件挺不过重启或扩容。
• 轮换初始 admin 密码。 引导 admin 账号带一个已知的开发密码——暴露应用前改掉它。
• 设置强 STACKRIVET_SECURITY_JWT_SECRET，所有密钥放环境里，绝不提交进代码仓库。
• Redis 必需——它支撑 JWT 吊销和健康检查。
• 限制 actuator/metrics 端点。 /actuator/health 和 /actuator/prometheus 按设计在管理端口上无需认证可达；生产中用网络 ACL 挡住。
• 托管、有备份的数据库。 用托管 MySQL/PostgreSQL，并有经过测试的备份恢复流程。

从卡住的启动恢复

症状	检查
port 8080 failed to start	lsof -nP -iTCP:8080 -sTCP:LISTEN——杀掉残留进程
密码正确却登录 401	STACKRIVET_SECURITY_JWT_SECRET 在 token 签发后被改过
Flyway checksum 不匹配	见数据库迁移 → 恢复

版本边界

Helm、多实例可用性与 SSO 集成不是已发布的 Community 能力，可通过范围明确的 Enterprise 试点评估——见价格页。Community 文档覆盖 Nginx 后的单应用实例部署。