lianlonggangandClaude Sonnet 4.6
e0231fca8f
- 新增 Harbor 镜像仓库查询、最新 tag 查询、skopeo 推送接口 - 新增 Choerodon DevOps 实例列表、Pod 状态、YAML 配置查询与更新接口 - 修复全局异常过滤器 404 日志刷屏问题 - 前端新增「镜像管理」和「控制台实例」Tab 页 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
150 lines
7.1 KiB
Markdown
150 lines
7.1 KiB
Markdown
# 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`）。
|