User Profiling System (UPS) v1.0

一个基于Spring Boot微服务架构的企业级用户画像系统，集成VOC（用户之声）Amazon评论AI分析能力。

✨ 特性

🏗️ 微服务架构 - 基于Spring Cloud的分布式系统
🔒 安全可靠 - JWT认证 + 强密码策略 + API限流
⚡ 高性能 - Redis缓存 + MongoDB索引优化
🔄 高可用 - 服务发现 + 熔断降级 + 分布式事务补偿
📊 完整画像 - 多维度用户行为分析和标签管理
🧪 测试完备 - 93个测试用例，75%+覆盖率
🤖 VOC分析 - 基于AI的Amazon评论四维价值模型分析

🛒 VOC 评论分析（新功能）

受 easy-amazon-voc 项目启发，集成 AI 驱动的跨境电商评论分析能力。

分析流程

用户上传 CSV 文件 (Amazon评论)
    ↓
Step 1: AI 生成四维标签体系（基于样本评论）
    ↓
Step 2: 逐条评论打标 + 情感分析
    ↓
Step 3: 汇总生成用户画像
    ↓
下载带分析标签的结果 CSV

四维价值模型

维度	分析维度
人群与场景	使用场景、购买动机、未被满足的需求、痛点问题
功能价值	产品优点、产品缺点、期望建议、设计与外观
保障价值	物流配送、售后服务、售前服务
体验价值	推荐意愿、品牌印象、感官感受、价格感知

使用方式

# 1. 使用 easy scraper 爬取 Amazon 商品评论，导出 CSV
# 2. 上传 CSV 启动分析
curl -X POST http://localhost:8080/api/v1/voc/upload \
  -F "file=@amazon_reviews.csv"
# 返回: {"jobId": "voc_xxx", "totalReviews": 200}

# 3. 查询分析进度
curl http://localhost:8080/api/v1/voc/status/voc_xxx

# 4. 完成后下载结果 CSV
curl -O http://localhost:8080/api/v1/voc/download/voc_xxx

# 5. 获取用户画像摘要
curl http://localhost:8080/api/v1/voc/profile/voc_xxx

配置 LLM API Key

在 .env 文件中配置：

LLM_API_KEY=sk-ant-your-key-here
LLM_MODEL=llm-3-5-sonnet-20241022

🚀 快速开始

环境要求

Docker 20.10+
Docker Compose 2.0+
4GB+ 可用内存

快速部署（推荐）

# 克隆项目
git clone https://github.com/dctx479/UPS.git
cd UPS

# 运行快速启动脚本
chmod +x quick-start.sh
./quick-start.sh

手动部署

# 克隆项目
git clone https://github.com/dctx479/UPS.git
cd UPS

# 配置环境变量
cp .env.example .env
vim .env  # 根据需要修改配置

# 验证环境变量配置（推荐）
chmod +x scripts/validate-env.sh
./scripts/validate-env.sh

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

重要: 运行 validate-env.sh 可以在启动前验证所有必需的环境变量，避免配置错误导致的启动失败。Windows用户请使用 scripts\validate-env.bat。

访问系统

API Gateway: http://localhost:8080
Consul UI: http://localhost:8500
Swagger API: http://localhost:8080/swagger-ui.html

📖 文档

核心文档

快速开始 - 5分钟快速部署指南
系统架构 - 技术架构和设计说明
API文档 - RESTful API接口文档
API版本控制 - API版本策略和废弃时间表
部署指南 - 生产环境部署
安全配置 - 安全配置指南和最佳实践
监控告警 - 监控告警配置和响应流程
用户使用指南 - 系统使用说明
故障排查 - 常见问题解决
产品路线图 - 未来功能规划和技术演进

架构图和设计文档

系统架构图 - 完整的系统架构设计
- 总体架构图（前端、网关、微服务、数据库、监控）
- 分层架构（表现层、业务层、数据层、基础设施层）
- 微服务架构（服务职责划分）
- 数据流向图（请求处理全流程）
- 部署架构（Docker容器化部署）
- 监控架构（Prometheus + Grafana）
- 高可用架构（服务集群和数据库主从）
数据库ER图 - 数据模型设计
- PostgreSQL实体关系图（users、user_tags、audit_logs）
- MongoDB文档结构（user_profiles）
- 索引设计和优化策略
- 数据关系说明
- 性能优化建议
业务时序图 - 核心业务流程
- 用户注册流程（含画像初始化）
- 用户登录流程（JWT认证）
- 画像更新流程（评分计算）
- 标签管理流程（CRUD操作）
- 用户事件处理流程（异步处理）
- 缓存预热流程（性能优化）

所有图表使用 Mermaid 语法绘制，在GitHub/GitLab上可直接查看渲染效果

云服务商部署指南

📍 完整索引

云服务器部署完整指南索引 - 推荐从这里开始

国内云服务商

腾讯云轻量应用服务器 - 腾讯云Lighthouse专属指南
阿里云ECS - 阿里云弹性计算服务专属指南
华为云ECS - 华为云弹性云服务器专属指南

国际云服务商

AWS EC2 - Amazon Web Services EC2专属指南
Azure虚拟机 - Microsoft Azure VM专属指南
Google Cloud Compute Engine - Google Cloud Platform专属指南

通用配置

公网访问配置 - 通用公网访问配置（适用所有云服务商）
快速公网配置 - 一键配置脚本使用指南

🏗️ 系统架构

Flutter Client
      ↓
API Gateway (8080)
      ↓
┌─────┴─────┬──────────┬──────────┐
↓           ↓          ↓          ↓
User     Profile     Tag       Consul
Service  Service  Service  (Registry)
(8081)   (8082)   (8083)     (8500)
↓           ↓          ↓
PostgreSQL  MongoDB    Redis

🛠️ 技术栈

后端

框架: Spring Boot 3.2, Spring Cloud
安全: Spring Security, JWT
服务治理: Consul, OpenFeign, Resilience4j
数据库: PostgreSQL, MongoDB, Redis

前端

UI框架: Flutter
状态管理: Provider

DevOps

容器化: Docker, Docker Compose
编排: Kubernetes
监控: Prometheus, Grafana
日志: ELK Stack

📦 项目结构

UPS/
├── backend/                 # 后端服务
│   ├── gateway-service/    # API网关
│   ├── user-service/       # 用户服务
│   ├── profile-service/    # 画像服务
│   └── tag-service/        # 标签服务
├── flutter-app/            # Flutter前端
├── scripts/                # 数据库初始化脚本
│   ├── postgresql-init.sql # PostgreSQL初始化
│   └── mongo-init.js      # MongoDB初始化
├── docs/                   # 文档
├── docker-compose.yml      # Docker Compose配置
├── deploy.sh              # 交互式部署脚本
└── quick-start.sh         # 快速启动脚本

🔧 开发

本地开发

# 启动基础设施
docker-compose up -d consul redis mongodb postgresql

# 启动服务 (需要 Maven 和 Java 17+)
cd backend/user-service
mvn spring-boot:run

cd backend/profile-service
mvn spring-boot:run

cd backend/tag-service
mvn spring-boot:run

cd backend/gateway-service
mvn spring-boot:run

Gateway路由配置

API网关是系统的统一入口，负责路由转发、限流保护、熔断降级等功能。

路由配置文件

backend/gateway-service/src/main/resources/application.yml

当前路由规则

路径	目标服务	功能	限流配置
`/api/v1/auth/**`	user-service	用户认证	50 RPS, 突发100
`/api/v1/users/**`	user-service	用户管理	100 RPS, 突发200
`/api/v1/profiles/**`	profile-service	用户画像	100 RPS, 突发200
`/api/v1/events/**`	profile-service	行为事件	100 RPS, 突发200
`/api/v1/segments/**`	profile-service	用户分群	100 RPS, 突发200
`/api/v1/recommendations/**`	profile-service	推荐服务	100 RPS, 突发200
`/api/v1/tags/**`	tag-service	标签管理	100 RPS, 突发200

如何添加新路由

编辑Gateway配置文件

vim backend/gateway-service/src/main/resources/application.yml

添加路由配置（在routes部分添加）

- id: your-service-v1              # 路由唯一标识
  uri: lb://your-service           # 目标服务（通过Consul负载均衡）
  predicates:
    - Path=/api/v1/your-path/**    # 路径匹配规则
  filters:
    - name: RequestRateLimiter     # 限流配置
      args:
        key-resolver: "#{@ipKeyResolver}"
        redis-rate-limiter.replenishRate: 100      # 每秒请求数
        redis-rate-limiter.burstCapacity: 200      # 突发容量
        redis-rate-limiter.requestedTokens: 1      # 每请求消耗令牌
    - name: CircuitBreaker         # 熔断配置
      args:
        name: yourServiceCircuitBreaker
        fallbackUri: forward:/fallback/your-service

添加熔断器配置（在resilience4j部分添加）

resilience4j:
  circuitbreaker:
    instances:
      yourServiceCircuitBreaker:
        slidingWindowSize: 10               # 滑动窗口大小
        minimumNumberOfCalls: 5             # 最小调用次数
        failureRateThreshold: 50            # 失败率阈值(%)
        waitDurationInOpenState: 10000      # 熔断等待时间(ms)
        permittedNumberOfCallsInHalfOpenState: 3  # 半开状态允许调用数

重启Gateway服务

cd backend/gateway-service
mvn spring-boot:run

验证路由

# 测试路由是否生效
curl http://localhost:8080/api/v1/your-path

# 查看Gateway注册的路由
curl http://localhost:8080/actuator/gateway/routes

限流配置建议

根据不同的API场景选择合适的限流参数：

场景	replenishRate	burstCapacity	requestedTokens	说明
登录/认证	50	100	1	短时突发，总量不高
查询接口	100	200	1	高频查询场景
写入接口	20	40	1	控制写入频率
批量操作	10	20	5	重量级操作
复杂查询	50	100	2-3	耗时查询、报表

熔断器配置说明

熔断器遵循三态模型：

Closed（关闭）: 正常状态，请求正常转发
Open（打开）: 熔断状态，直接返回降级响应
Half-Open（半开）: 尝试恢复，允许少量请求测试服务

关键参数：

slidingWindowSize: 统计窗口大小（建议10-20）
failureRateThreshold: 失败率阈值（建议30-50%）
waitDurationInOpenState: 熔断等待时间（建议10-30秒）

监控和调优

查看Gateway实时状态：

# 健康检查
curl http://localhost:8080/actuator/health

# 查看所有路由
curl http://localhost:8080/actuator/gateway/routes

# 查看限流统计
curl http://localhost:8080/actuator/metrics/spring.cloud.gateway.requests

# 查看熔断器状态
curl http://localhost:8080/actuator/metrics/resilience4j.circuitbreaker.state

监控指标：

429错误率 < 5%（限流触发率）
平均响应时间 < 1s
熔断器Open状态占比 < 1%
服务器CPU/内存使用率 < 70%

常见问题

Q: 路由不生效怎么办？ A:

检查路由顺序（更具体的路由要放在前面）
验证Path匹配规则是否正确
确认目标服务已注册到Consul
查看Gateway日志：docker logs gateway-service

Q: 频繁出现429错误？ A:

检查限流配置是否过于严格
提高replenishRate和burstCapacity
根据实际流量调整参数
考虑使用用户级限流而非IP级限流

Q: 服务经常被熔断？ A:

检查后端服务健康状态
调整failureRateThreshold（提高容错率）
增加waitDurationInOpenState（给服务更多恢复时间）
优化后端服务性能

详细配置说明和最佳实践请参考：

Gateway配置文件：backend/gateway-service/src/main/resources/application.yml
官方文档：https://docs.spring.io/spring-cloud-gateway/reference/

调整评分规则配置

系统的用户画像评分规则支持完全配置化，无需修改代码即可调整评分策略。

配置文件位置

backend/profile-service/src/main/resources/application-scoring.yml

主要配置项

评分权重 - 调整各维度对综合评分的影响

scoring:
  weights:
    digital-behavior: 0.30  # 数字行为权重
    value-assessment: 0.40  # 价值评估权重
    stickiness: 0.30        # 粘性权重

数字行为评分规则

digital-behavior:
  product-categories:
    score-per-category: 8   # 每个品类的分数
    max-score: 40          # 品类评分上限
  brand-preferences:
    score-per-brand: 10    # 每个品牌的分数
    max-score: 30          # 品牌评分上限

用户分级阈值

user-type:
  high-value-threshold: 80.0   # 高价值用户阈值
  active-threshold: 60.0       # 活跃用户阈值
  potential-threshold: 40.0    # 潜力用户阈值
  normal-threshold: 20.0       # 普通用户阈值

配置调整步骤

编辑配置文件 application-scoring.yml
修改需要调整的参数值
重启 profile-service 服务使配置生效
系统会自动验证权重总和是否为1.0

配置示例

场景1: 更重视用户消费能力

weights:
  digital-behavior: 0.25
  value-assessment: 0.50  # 提高价值评估权重
  stickiness: 0.25

场景2: 降低VIP门槛

tags:
  vip-threshold: 70.0     # 从80降至70
  quality-threshold: 50.0  # 从60降至50

详细的评分规则说明和调优建议请参考配置文件中的注释。

运行测试

# 运行所有测试
cd backend
mvn test

# 运行集成测试
mvn test -Dtest=*IntegrationTest

📊 功能模块

用户管理

用户注册、登录、认证
密码加密和强密码策略
JWT Token管理
审计日志记录

画像管理

多维度用户画像
自动画像初始化
画像评分计算
用户类型分析
价值评估
可配置评分规则 - 支持通过配置文件灵活调整评分权重和规则

标签管理

灵活的标签系统
标签权重管理
批量操作
标签分类

🔄 API 版本策略

当前版本

v1 (稳定版): /api/v1/* - 支持至 2026-12-31
Legacy API (已废弃): /api/* - ⚠️ 兼容期至 2025-12-31，之后移除

废弃时间表

路径	状态	兼容期截止	移除日期
`/api/auth/**`	已废弃	2025-12-31	2026-01-01
`/api/users/**`	已废弃	2025-12-31	2026-01-01
`/api/profiles/**`	已废弃	2025-12-31	2026-01-01
`/api/tags/**`	已废弃	2025-12-31	2026-01-01

未来规划

v2 (规划中): 预计 2026-Q2 发布，包含 GraphQL 支持、批量操作优化等

详细信息请参阅 API 版本控制文档。

迁移建议

如果您正在使用 Legacy API（不带版本号），请尽快迁移到 v1：

# 旧版本 (将在 2026-01-01 移除)
curl http://localhost:8080/api/users

# 新版本 (推荐使用)
curl http://localhost:8080/api/v1/users

🔐 安全特性

✅ JWT Token认证
✅ 密码BCrypt加密
✅ 强密码策略 (8位+，包含大小写字母、数字、特殊字符)
✅ API限流保护 (基于IP)
✅ 完整审计日志
✅ CORS跨域配置

CORS跨域配置

系统提供了完善的CORS配置，支持开发和生产环境的不同安全策略。

配置位置

开发环境: backend/gateway-service/src/main/resources/application.yml
生产环境: backend/gateway-service/src/main/resources/application-prod.yml

快速配置

使用环境变量 ALLOWED_ORIGINS 配置允许的前端域名：

# 开发环境 (.env)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# 生产环境 (.env)
ALLOWED_ORIGINS=https://app.yourdomain.com,https://www.yourdomain.com

配置差异

配置项	开发环境	生产环境
允许的域名	localhost:*	具体HTTPS域名列表
允许的请求头	* (所有)	明确指定(Authorization, Content-Type等)
允许的方法	GET, POST, PUT, DELETE, OPTIONS	GET, POST, PUT, DELETE, OPTIONS
预检缓存时间	3600秒	3600秒
允许携带凭证	✅ 是	✅ 是

安全最佳实践

生产环境必须使用HTTPS域名

# ✅ 正确
ALLOWED_ORIGINS=https://app.example.com,https://www.example.com

# ❌ 不安全
ALLOWED_ORIGINS=http://app.example.com,*

不使用通配符

# ❌ 避免使用通配符
ALLOWED_ORIGINS=*

# ✅ 明确指定域名
ALLOWED_ORIGINS=https://app.example.com,https://m.example.com

生产环境限制请求头

生产环境配置文件已限制为必需的请求头：
- Authorization (JWT认证)
- Content-Type (请求体类型)
- Accept (响应类型)
- X-Requested-With (AJAX标识)
- X-Request-ID (请求追踪)

常见CORS错误解决

错误1: No 'Access-Control-Allow-Origin' header is present

# 原因: 前端域名不在允许列表中
# 解决: 将域名添加到 ALLOWED_ORIGINS
ALLOWED_ORIGINS=https://app.example.com,https://your-frontend.com

错误2: The value of 'Access-Control-Allow-Origin' must not be '*'

# 原因: allowCredentials为true时不能使用通配符
# 解决: 明确指定域名列表，不使用*
ALLOWED_ORIGINS=https://app.example.com

错误3: Request header field XXX is not allowed

# 原因: 生产环境限制了允许的请求头
# 解决: 在 application-prod.yml 的 allowedHeaders 中添加该请求头
spring:
  cloud:
    gateway:
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedHeaders:
              - Authorization
              - Content-Type
              - Your-Custom-Header  # 添加自定义请求头

调试技巧

查看OPTIONS预检请求

# 使用浏览器开发者工具 Network 面板
# 查看 OPTIONS 请求的响应头

使用curl测试CORS

curl -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Authorization" \
     -X OPTIONS \
     http://localhost:8080/api/v1/users

启用Gateway调试日志

logging:
  level:
    org.springframework.cloud.gateway: DEBUG

生产环境部署检查清单

部署到生产环境前，请确认：

✅ ALLOWED_ORIGINS 已设置为实际的前端HTTPS域名
✅ 未使用通配符 * 或 localhost
✅ 所有域名都使用HTTPS协议
✅ allowedHeaders 已限制为必需的请求头（非*）
✅ 测试跨域请求正常（登录、API调用等）
✅ 验证未授权域名无法访问

详细配置说明请参考配置文件中的注释。

📈 性能优化

✅ Redis缓存层
✅ MongoDB索引优化 (查询性能提升100倍)
✅ 数据库连接池
✅ 分页查询
✅ 异步处理

🔄 高可用

✅ Consul服务发现
✅ 客户端负载均衡
✅ 熔断降级机制
✅ 分布式事务补偿
✅ 健康检查

🧪 测试

单元测试: 60个测试用例
集成测试: 33个端到端测试
总测试数: 93个
覆盖率: 75%+

📝 版本信息

当前版本: v1.0 状态: ✅ 生产就绪

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

本项目采用 CC BY-NC 4.0 (Creative Commons Attribution-NonCommercial 4.0 International) 许可协议。

允许:

✅ 个人学习和研究
✅ 非商业用途的使用和修改
✅ 在署名的前提下分享和传播

禁止:

❌ 商业用途（包括但不限于商业产品、付费服务、盈利活动）
❌ 未经授权的商业化部署

如需商业授权,请联系: b150w4942@163.com

详细协议内容请查看 LICENSE 文件。

👨‍💻 作者

GitHub: @dctx479
Email: b150w4942@163.com

🙏 致谢

感谢所有开源项目和社区的支持！

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
backend		backend
deployment		deployment
docs		docs
flutter-app		flutter-app
frontend		frontend
monitoring		monitoring
reports		reports
scripts		scripts
testing		testing
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.project-rules		.project-rules
COMPLIANCE.md		COMPLIANCE.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
e3041b53cb010015cf7b2544abf0e4a8.jpg		e3041b53cb010015cf7b2544abf0e4a8.jpg
quick-start.sh		quick-start.sh
setup-public-access.sh		setup-public-access.sh
test-api.sh		test-api.sh
verify-content.sh		verify-content.sh

Folders and files

Latest commit

History

Repository files navigation