进行中网页应用
CampusTrade
校园二手交易平台 —— 校园闲置交易与信用体系
面向高校的二手交易平台：校园身份认证（邮箱 / 学号双通道）作为发布硬前置，注册到评价的完整交易闭环与 100 分初始信用档案，单端口边缘网关交付，线上 40+ 接口 / 60+ 断言验收。
角色 独立开发：后端 / Flutter 客户端 / 生产编排 / 上线部署与线上验收 / 文档
- Java 21
- Spring Boot 3.3.4
- MyBatis-Plus 3.5.7
- JWT + 刷新令牌吊销
- Flyway（V1–V13，Schema 单一真相源）
- Testcontainers
- Flutter 3 / Dart 3
- GetX（状态管理 + 路由）
- 还有 20 项技术
概览
面向高校的二手交易平台，把「注册 → 校园身份认证（两条通道）→ 发布商品（图片上传）→ 搜索 / 收藏 / 足迹 → 下单 → 卖家确认 → 完成 → 双向评价 → 信用分」做成一条完整可信的闭环，并配有举报与管理端治理（认证审核 / 举报驳回处置 / 审计日志）。
技术栈为 Spring Boot 3.3.4 + Java 21 + MyBatis-Plus + PostgreSQL 16 + Redis 7.4 + MinIO（S3 兼容私有对象存储），客户端为 Flutter 3 + GetX，生产用 Docker Compose 单端口边缘网关交付，已上线并完成真实 HTTP 全链路验收。
问题
校园二手交易信息散落在 QQ 群、表白墙，缺少身份与信用约束：校外人员也能随意发布，交易出问题没有留痕。
交易过程没有状态跟踪：谁下单、谁确认、能否取消、评价与信用如何沉淀，全靠私下聊天。
用户上传的图片如果直连对象存储，等于把存储服务暴露在公网；同时用户内容（描述、评价）若不转义，会带来 XSS 风险。
目标
建一条可信的交易闭环：校园身份认证作为发布硬前置，交易全程有状态、有评价、有信用沉淀。
安全与合规：对象存储不暴露公网、用户内容统一转义、Schema 有单一真相源、反代与可信 IP 配置明确。
工程可交付：一键启动、质量门禁脚本、测试与开发数据隔离、镜像可复现、上线前检查清单。
方案
对外只保留一个边缘入口：edge nginx 暴露 8080，把 / 交给 Flutter Web 静态产物、/api 反代后端、/img 反代 MinIO，数据库、缓存与对象存储三者完全不暴露公网。
校园认证设计成两条通道写同一张表：邮箱通道做学校后缀校验与验证码核销，学号通道只填学校与学号并交给管理员人工审核，用 verify_method 区分来源，下游的发布闸门与认证标识不感知差异。
交易状态机覆盖下单、卖家确认、完成与取消，成交后双方信用 +2，评价按订单唯一；举报进入管理端处置队列，每次处置都写审计日志。
质量与测试环境自洽：后端测试用 Testcontainers 在测试 JVM 内现拉 PostgreSQL / Redis / MinIO，测试绝不读写开发库；quality-gate 脚本先探测 Docker 可用性再依次跑后端测试与前端 analyze / test。
架构
Flutter Web / App 客户端（GetX 状态与路由、Dio 拦截器与 Token 自动刷新、Flutter Secure Storage 存放敏感凭证）访问公网 8080，由 edge nginx 作为唯一对外入口：/ 提供 Flutter Web 静态产物（SPA 深链接回退、入口文件 no-cache、带内容哈希的资源长缓存），/api 反代 Spring Boot（内网 8081：认证 / 商品 / 订单 / 评价 / 举报 / 治理 / AI），/img 反代 MinIO（9000，控制台与 S3 API 均不暴露公网）。内网为 PostgreSQL 16（Flyway V1–V13 迁移）与 Redis 7.4（会话 / 限流 / 验证码 / 分布式锁）。
对象存储只经反代读取，不直接对外
- 背景
- 商品图片需要公网访问，但 MinIO 的控制台与 S3 API 不应暴露在公网。
- 选择
- 由边缘 nginx 把 /img 反代到内网 MinIO，存储服务本身不出公网
- 原因
- 对外只剩一个入口，缓存策略、鉴权与可信 IP 的配置都集中在一处；对象存储的攻击面不暴露。
- 考虑过的方案
- 给 MinIO 绑定域名直接对外
- 用预签名 URL 让客户端直连
- 由边缘 nginx 反代 /img 读取
- 代价
- 图片流量全部经过边缘网关，网关的静态与反代规则必须写对，否则会出现「上传成功但访问 404」。
认证扩通道时保持下游不感知
- 背景
- 校园认证从一条通道扩到两条，但发布闸门、认证标识与信用逻辑不应因此分叉。
- 选择
- 两条通道写同一张表，用 verify_method 区分来源，状态域新增 REJECTED，并为人工通道单独建立 (school_id, student_number) 的 SUCCESS 部分唯一索引
- 原因
- 下游只关心「是否通过认证」这一个事实，把差异压在写入侧可以避免到处分支。
- 代价
- 迁移需要处理历史冲突数据：发现冲突时跳过建索引并打印明细，而不是删改用户数据。
生产邮件未接通时，用白名单演示模式而不是关闭校验
- 背景
- 校园认证是发布商品的硬前置，但生产 SMTP 还是占位账号，真实验证码发不出去。
- 选择
- 白名单邮箱的验证码随响应返回并由前端自动填入，白名单之外仍走真实校验与发送失败不降级
- 原因
- 演示可用性不应该以削弱校验为代价；把口子限定在白名单内，并加启动 WARN 与「开了开关却没写白名单就拒绝启动」的护栏。
- 考虑过的方案
- 临时关闭认证校验
- 等邮件通道接通再说
- 只对白名单邮箱跳过真实发送
- 代价
- 线上存在一个必须记得关闭的开关，因此用启动告警把它暴露出来。
技术栈
后端
- Java 21
- Spring Boot 3.3.4
- MyBatis-Plus 3.5.7
- JWT + 刷新令牌吊销
- Flyway（V1–V13，Schema 单一真相源）
- Testcontainers
前端
- Flutter 3 / Dart 3
- GetX（状态管理 + 路由）
- Dio（拦截器 + Token 自动刷新）
- Flutter Secure Storage
数据库
- PostgreSQL 16
- Flyway V1–V13 迁移
- NOT VALID 外键 + 校园邮箱部分唯一索引
- (school_id, student_number) SUCCESS 部分唯一索引
中间件
- Redis 7.4（AOF + 强制口令）
- 会话 / 限流 / 验证码 / 分布式锁 / 浏览量计数
- MinIO（S3 兼容私有对象存储）
- edge nginx 单端口边缘网关
AI
- 商品描述生成
- 分类推荐
- 价格区间估算（未配置 Key 时本地规则降级）
测试
- 后端 263 用例（Testcontainers 提供真实 PostgreSQL / Redis / MinIO）
- 前端 210 用例 + flutter analyze
- 线上 HTTP 全链路验收脚本
DevOps 与基础设施
- Docker Compose 生产编排（edge nginx + app + minio + postgres + redis）
- quality-gate 一键门禁脚本
- GitHub Actions CI
- 部署文档与上线检查清单
基础设施
- 单端口边缘网关：对外只暴露 8080，/api 与 /img 分别反代后端与 MinIO
- 五个容器全部 restart=unless-stopped，部署在腾讯云 CVM（4 核 / 3.6G，Ubuntu 24.04）
- 缓存策略区分：带内容哈希的静态资源长缓存，Flutter 入口文件 no-cache，避免发版后用户拿到旧前端
技术亮点
单端口边缘网关
对外只暴露 8080，/api 与 /img 分别反代后端与 MinIO，数据库 / 缓存 / 对象存储三者完全不暴露公网；同时区分缓存策略，带内容哈希的资源长缓存、入口文件 no-cache。
Schema 单一真相源
Flyway 管理全部结构变更；用 NOT VALID 外键 + 校园邮箱部分唯一索引，兼顾历史脏数据与约束强度。
测试与开发数据隔离
后端测试用 Testcontainers 在测试 JVM 内现拉 PostgreSQL / Redis / MinIO（镜像 tag 固定，与 compose 一致），测试绝不读写开发库。
质量门禁
quality-gate.ps1 先探测 Docker 是否可用（不可用给中文原因并以非 0 退出，而不是把英文异常抛进日志），再依次跑后端测试与前端 analyze / test。
安全细节
用户输入内容统一转义、可信 IP 与反代配置、上线前清理 Redis 中历史明文 refresh token、镜像 tag + digest 与代码版本一一对应。
真实上线验收
不是「跑通接口就算」，而是对生产实例发真实 HTTP，按完整闭环跑 40+ 接口 / 60+ 断言，并把发现的问题与处理写进验收报告。
难点与取舍
商品图片全部 404（伪装性很强的线上缺陷）
- 问题
- 上传返回 200、容器内直连 MinIO 也 200，只有从边缘访问是 404。
- 做法
- 用「容器内直连 vs 边缘访问」做二分，把排查范围压到反代层；定位到 nginx 的 location 匹配顺序——正则 location 优先于前缀 location，后加的正则静态资源规则把 /img/ 请求截走去找本地文件了。
- 结果
- 给 /img/ 与 /api/ 加上 ^~ 前缀修饰符后复验返回 200 image/png，并留下「先二分定位层次，再看该层规则」的排查手法。
认证前置与演示可用性的冲突
- 问题
- 校园认证是发布商品的硬前置，但生产 SMTP 仍是占位账号，真实验证码发不出去。
- 做法
- 设计白名单演示模式：仅白名单邮箱跳过真实邮件，验证码随响应返回供前端自动填入；白名单外仍走真实校验，发送失败不降级。
- 结果
- 演示链路可用，同时用启动 WARN 与「开了开关却没写白名单就拒绝启动」的护栏避免开关被遗忘。
数据库约束演进
- 问题
- 历史数据存在脏值时，直接加外键或唯一索引会失败。
- 做法
- 使用 NOT VALID 外键与分批清理流程，并把「上线前必做」的清理步骤写进部署文档。
- 结果
- 约束强度与历史数据兼容同时满足。
测试环境自洽
- 问题
- 测试要真连中间件又不能污染开发数据；门禁脚本若加载 .env，会把开发环境的 Redis 口令带进临时容器导致 AUTH 失败。
- 做法
- Testcontainers 内嵌拉起并固定镜像 tag，门禁脚本刻意不加载 .env。
- 结果
- 测试可重复运行，也不再受开发环境配置干扰。
第二条认证通道的表结构演进
- 问题
- 认证从一条通道扩到两条，但下游（发布闸门、认证标识、信用）不应该感知差异，还要防止「一学号多绑」。
- 做法
- 同一张表加 verify_method 区分来源、状态域新增 REJECTED，并为人工通道单独建 (school_id, student_number) 的 SUCCESS 部分唯一索引；迁移时若发现历史冲突则跳过建索引并打印明细。
- 结果
- 两条通道的认证结果语义完全一致，历史数据不被删改。
并发处置的一致性
- 问题
- 两个管理员同时点同一条审核时，可能出现重复审核或相互覆盖。
- 做法
- 用条件更新（WHERE status = 'PENDING'）+ 受影响行数判断「谁先处置谁生效」，每次处置都写 admin_audit_log。
- 结果
- 同一申请只会被处置一次，处置过程全程可查。
发布成功却提示失败
- 问题
- 页面跳转写在 try 块内，跳转失败会把「发布成功」误报为失败，用户重复点击导致同一商品发到 9 件。
- 做法
- 把跳转移出 try 并加发布锁；同时把操作反馈统一成「进行中 / 成功（带下一步）/ 失败（带重试）」三态。
- 结果
- 重复发布被消除，用户能明确知道当前状态与下一步动作。
管理端列表崩溃
- 问题
- 后端 total 在某些序列化路径下是字符串，前端按 int 解析直接崩溃。
- 做法
- 统一走 asInt 容错解析，并把提交时间格式化为可读格式。
- 结果
- 同一份数据在不同序列化路径下都能正确渲染。
权衡取舍
对象存储的对外方式
选了 边缘 nginx 反代 /img，而不是 让 MinIO 直接对公网提供访问 —— 唯一入口便于统一缓存、鉴权与可信 IP 配置，也避免把存储服务暴露出去。
代价：所有图片流量都经过网关，反代规则写错会出现「上传成功但访问 404」这类难查的缺陷。
测试数据的隔离方式
选了 Testcontainers 在测试 JVM 内现拉 PostgreSQL / Redis / MinIO，而不是 共用一个开发用数据库 —— 测试可以真连中间件，同时保证结果不受开发数据影响、也不会反向污染开发库。
代价：跑测试必须能拉取镜像，单次执行比纯内存替身更慢。
认证通道的扩展方式
选了 同一张表 + verify_method 区分来源，而不是 为人工通道单独建一张表 —— 下游只关心认证是否通过，单表能让发布闸门与信用逻辑保持一条路径。
代价：表结构与索引更复杂，迁移时还要处理历史冲突数据。
结果
后端：mvn -B test 263 项全绿，由 Testcontainers 提供真实 PostgreSQL 16 / Redis 7.4 / MinIO；前端：flutter analyze 无问题、flutter test 210 项全部通过（仓库 README 记录的 194 是旧基线）。
线上部署（2026-09-22 验收 + 本次复核）：https://trade.myiskg.com/ 已上线运行于腾讯云 CVM（4 核 / 3.6G，Ubuntu 24.04），edge nginx + app + minio + postgres + redis 五个容器全部 restart=unless-stopped；自 2026-09-24 起启用 HTTPS。首页可匿名浏览商品，体验发布与交易需注册并完成校园认证（演示邮箱可跳过真实邮件取码）。
线上验收覆盖：按「注册 → 登录 → 认证 → 发布 → 交易 → 评价 → 举报 → 治理」完整闭环，15 个业务域、40+ 接口、60+ 断言全部通过（过程中发现 1 个真实缺陷，已修复并复验）。
新功能线上端到端（2026-09-23）：注册 → 提交学号材料（PENDING/MANUAL）→ 未认证发布被拒 400 → 管理员队列可见 → 驳回不写原因 400 → 驳回（REJECTED，学生看到原因）→ 重提（PENDING，原因清空）→ 通过（SUCCESS）→ 发布成功 → 审计流水 PASS_STUDENT_VERIFY，线上已执行 V13 迁移。
数据卫生：验收用的临时账号、商品、订单、评价、举报、MinIO 对象与 Redis 键全部清理，线上库仅保留开发者本人账号。
仓库：GitHub 公开仓库，32 次提交，最新提交 2026-09-23，含后端、Flutter 客户端、生产编排、部署文档与各阶段审计报告。
收获
线上缺陷的排查顺序比经验更重要：「容器内直连正常、只有边缘访问失败」这一个对比，就把问题从存储层锁到了反代层。
演示需求不该用削弱校验来满足：把口子限定在白名单、并对开关本身加护栏，才能在可用与安全之间取得平衡。
测试与开发环境必须物理隔离：Testcontainers 加上刻意不加载 .env 的门禁脚本，才算真正把「测试不污染开发数据」落到工程上。
截图
线上实测：欢迎条 + 搜索框 + 最新商品列表，含成色标签与价格 
线上实测：CampusTrade 登录页 
线上实测：注册页，注明「注册即自动建立初始 100 分信用档案」 
线上实测：搜索 + 热搜词 + 分类筛选 + 商品卡片 
线上实测：商品详情，含原价 / 成色 / 商品说明 / 卖家信用与认证标识 / 评价区 / 立即下单 
线上实测：发布页，含 AI 帮写描述 / 智能分类 / 智能估价入口与认证硬闸门弹窗 
线上实测：校园身份认证页，含邮箱验证码通道与学号认证入口 
线上实测：第二种认证通道——只填学校 + 学号，提交后由管理员人工审核 
线上实测：个人中心，含校园认证状态、信用档案 100 分与交易 / 评价统计 
线上实测：我的订单页