# 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`）。