xj-oss-syn/CLAUDE.md

xj-oss-syn 项目说明

项目目标

1. OSS 同步：将业务系统中存储在本地的文件批量上传到新疆油田 IOSP OSS 平台，并将业务表中的文件路径更新为 OSS 路径。
2. 镜像管理：通过 Harbor API + skopeo CLI 查询镜像仓库列表、最新 tag，并支持将 tar 包推送到 Harbor。
3. 控制台实例管理：通过 Choerodon DevOps API 查询实例列表、Pod 状态、YAML 配置，并支持更新配置。

技术栈

• 框架：Solon 3.10.0
• ORM：MyBatis-Plus（solon 插件）
• 数据库：MySQL 8.x（HikariCP 连接池）
• HTTP 客户端：Java 内置 java.net.http.HttpClient（trust-all SSLContext，支持 NEVER/NORMAL 重定向策略）
• JSON：Fastjson2
• 认证：Sa-Token（单账号 HTTP Basic，凭证来自 sa-token.http-basic 配置）
• 模板引擎：FreeMarker（src/main/resources/templates/）
• 构建：Maven + solon-maven-plugin

包结构

com.yxtech.ossyn
├── App.java                             # 启动入口
├── config/
│   ├── BizDataSourceConfig.java         # 业务库连接公共参数
│   ├── BizFileMappingConfig.java        # 业务表映射配置（来自 yml）
│   ├── ConsoleConfig.java               # Choerodon 控制台参数
│   ├── HarborConfig.java                # Harbor 镜像仓库参数
│   ├── LocalFileConfig.java             # 本地文件根路径
│   ├── MybatisPlusConfig.java           # MyBatis-Plus 分页插件等
│   ├── OssConfig.java                   # OSS 连接参数
│   ├── SaTokenConfig.java               # Sa-Token 路由白名单
│   └── SkopeoConfig.java                # skopeo 可执行文件及镜像目录
├── controller/
│   ├── AuthController.java              # 登录/登出页面（/auth/*）
│   ├── BizFileMappingController.java    # 映射配置 CRUD 接口
│   ├── DevopsController.java            # 镜像管理 + 控制台实例接口（/devops/*）
│   └── OssSyncController.java          # OSS 同步触发接口（/oss-sync/*）
├── entity/
│   ├── BizFileMappingEntity.java        # 业务表映射配置实体
│   ├── QhOssFileLog.java                # 文件转换日志实体
│   └── SyncTask.java                    # 同步任务实体
├── filter/
│   └── GlobalExceptionFilter.java       # 全局异常处理（404 DEBUG / 其他 ERROR）
├── mapper/
│   ├── BizFileMappingMapper.java
│   ├── QhOssFileLogMapper.java
│   └── SyncTaskMapper.java
├── service/
│   ├── ConsoleService.java              # Choerodon 控制台 API（token 缓存 + 401 重试）
│   ├── HarborService.java               # Harbor API + skopeo push（trust-all SSL）
│   └── OssSyncService.java             # OSS 同步核心逻辑
└── util/
    ├── DynamicDataSourceUtil.java       # 动态数据源（按 dbName 创建连接池）
    └── OssUtil.java                     # OSS 上传工具（内存缓存 token）

数据库

• 数据源1（本项目）：存储 QH_OSS_FILE_LOG 日志表，建表脚本见 sql/init.sql
• 数据源2（业务库）：动态创建，根据 biz-file-mappings 配置的 dbName 连接

配置说明（app.yml）

配置项	说明
solon.dataSources.db1!	本项目数据库连接
server.request-maxBodySize	请求体大小上限（当前 1GB，支持大镜像上传）
biz-datasource	业务库公共连接参数（host/port/user/pass）
biz-file-mappings	业务表映射列表（dbName/tableName/idCol/fileCol）
local-file.root-path	本地文件根路径
xj-oss.*	OSS 网关、鉴权、目录等参数
harbor.*	Harbor 地址、项目名、账号密码
skopeo.exe-path	skopeo.exe 可执行文件路径
skopeo.images-path	镜像 tar 包存放目录
console.api-base	Choerodon DevOps API 网关地址
console.project-id	控制台项目 ID
console.env-id	控制台环境 ID
console.login-username/password	控制台登录账号
console.public-key	控制台 RSA 公钥（用于密码加密）
sa-token.http-basic	本系统登录凭证（格式：用户名:密码）

敏感配置（密码、密钥等）可通过 app-env.yml 覆盖，该文件不纳入版本管理。

HTTP 接口

认证（AuthController）

接口	说明
GET /auth/login	显示登录页
POST /auth/doLogin	处理登录（凭证来自 sa-token.http-basic）
GET /auth/logout	退出登录

OSS 同步（OssSyncController）

接口	说明
POST /oss-sync/all	一键全量同步（扫描+上传+回写）
POST /oss-sync/scan	仅扫描业务表，写入日志
POST /oss-sync/upload	仅上传待处理文件
POST /oss-sync/write-back	仅回写业务表

DevOps（DevopsController）

接口	说明
GET /devops/harbor/repositories	查询 Harbor 镜像仓库列表
GET /devops/harbor/latest-tag?repo=	查询指定仓库最新 tag
POST /devops/harbor/push	上传 tar 包并推送到 Harbor（multipart，自动计算下一个 tag）
POST /devops/console/instances	查询所有实例（全量 size=500）
POST /devops/console/pods	查询实例 Pod 列表
GET /devops/console/yaml	查询实例 YAML 配置
PUT /devops/console/yaml	更新实例 YAML 配置

OSS 处理状态说明

值	含义
0	待处理
1	上传成功
2	上传失败
3	文件不存在
4	已回写业务表

关键设计说明

Choerodon 控制台登录流程

登录需要两步（均需要 NEVER 重定向策略才能拿到 302 响应头）：

1. POST /oauth/choerodon/login → 收集响应中所有 Set-Cookie（allValues），拼成完整 Cookie 字符串
2. GET /oauth/oauth/authorize 携带 Cookie → 从 302 响应的 Location URL fragment（# 后）提取 access_token

• authClient：NEVER 重定向（登录/授权专用）
• apiClient：NORMAL 重定向（业务请求专用）
• token 内存缓存，有效期 ~24h；收到 401 自动清除缓存并重试一次

SSL 证书

内部域名使用自签证书，HarborService.buildTrustAllClient() 构造 trust-all SSLContext， 所有 HttpClient 实例均通过该方法创建，跳过证书验证。

镜像上传（skopeo）

skopeo copy --dest-creds user:pass --dest-tls-verify=false \
  docker-archive:{tarAbsPath} \
  docker://{harborHost}/{project}/{repo}:{tag}

• tar 包按日期子目录存放（imagesPath/yyyyMMdd/filename.tar）
• tag 自动在最新 tag 基础上末位 +1（如 1.0.10 → 1.0.11）

注意事项

• 扫描阶段幂等，同一业务表+ID+列已存在日志则跳过
• OSS token 使用内存缓存，无需 Redis
• 动态数据源按 dbName 缓存连接池，避免重复创建
• 业务库列名/表名来自内部配置，不存在 SQL 注入风险
• 文件上传暂不支持 JSON 类型（TXX-19，待排查）

Linear 任务追踪

所有功能任务和 Bug 统一记录到 Linear tar-update 项目（团队 txxz）。