LiuMangMang/svn-log-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
53f8b2e21b5d20bbdb7904bf7f29e6f4b619057d
svn-log-tool/docs/README_Web.md
T
liujing 53f8b2e21b feat: support git repositories and project management 
- Git (JGit) log fetching: mirror clone cache, incremental fetch, time/author filter, HTTPS token & SSH key auth
- Git preset management and /api/git/* endpoints (test-connection, version-range, fetch)
- Markdown report generalization: project meta, commit range, short hash entries
- Project management: project entities, drag-drop repo assignment, sorting, rename sync, non-empty delete protection
- AI analysis: project-based grouping merges SVN+Git commits, excludes empty projects from Excel
- Batch fetch: skip repos without logs instead of aborting the whole flow
- Frontend: project management page, repo page project dropdown, Git fields, sidebar updates
- Tests: GitLogFetcherTest, DateRangeResolverTest, ProjectConfigServiceTest, merge/exclusion coverage
2026-07-31 21:19:12 +08:00

8.1 KiB
Raw Blame History

SVN 日志 Web 工作台

功能概览

Web 工作台将现有 CLI 能力封装为可视化页面与 REST API，支持以下流程：

  1. 仓库参数录入与连接测试（SVN / Git 两种类型）
  2. 异步抓取日志并导出 Markdown
  3. 使用 DeepSeek 或 OpenAI 兼容接口分析 Markdown 并生成 Excel
  4. 查看任务历史（状态、进度、错误、产物），支持筛选、分页与取消运行中任务
  5. 下载输出文件、配置 API Key、SVN 账号与输出目录
  6. 工作台展示系统健康状态（输出目录可写性、API Key 配置、任务统计）

批量抓取策略：多个项目（SVN + Git 可混合）按顺序执行（前一个项目完成后才开始下一个），最终汇总为一份 Excel 整体报告。

启动方式

在仓库根目录执行：

# Docker 一键启动（推荐；每次会重新构建镜像并打包最新代码）
make up

备用方式（本机 Java + Maven）：

mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication

启动后访问：

http://localhost:18088

Docker 构建行为与优化

  • Docker 镜像加速：默认使用 docker.1ms.run/library 代理。如果需要切换回 Docker Hub 或使用国内其他镜像（如阿里云镜像，例如 registry.cn-hangzhou.aliyuncs.com/library，注意不能带 https://），可以通过命令行传递 DOCKER_REGISTRY_MIRROR 变量： 
    DOCKER_REGISTRY_MIRROR=registry.cn-hangzhou.aliyuncs.com/library make up
  • 快速开发迭代（可选 Fast Build）：默认情况下，构建仍会执行 mvn clean package 以确保打包的正确性（防旧 class 或资源残留）。如果在本地频繁修改 Java 代码，可以使用 fast-up 实现秒级编译与构建重启。注意：如果修改了前端静态资源，或删除/重命名了 Java 类与资源文件，应使用默认构建（make up），不要用 Fast Build。 
    make fast-up
    该模式下，Docker 会使用 BuildKit 挂载缓存 /app/target 目录，并不再执行 clean 目标，使 Maven 能进行增量编译。
  • 依赖缓存：Docker 构建使用 BuildKit 缓存了 Maven 本地仓库（.m2）与 npm 缓存（.npm）。在依赖文件未变更时，不会重复下载依赖包。
  • 如果本机 Docker 未启用 BuildKit，可显式设置 DOCKER_BUILDKIT=1 和 COMPOSE_DOCKER_CLI_BUILD=1 后再执行构建。

页面说明

  • 工作台：最近任务统计与最近产物
  • 日志抓取：选择 SVN / Git 仓库（可混合），选时间范围（月/周/日）、过滤用户与连接测试；SVN 自动填充版本号，Git 直接按时间范围抓取
  • AI 工作量分析：选择 Markdown 文件、工作周期、输出文件名；SVN 与 Git 报告可多选合并，按项目归类生成整体 Excel
  • 任务历史：异步任务状态与产物列表，支持筛选、分页、取消任务
  • 仓库管理：SVN / Git 预设 CRUD、连接测试；Git 预设支持分支（留空自动探测）、HTTPS Token 或 SSH 私钥认证
  • 系统设置：AI 提供商、DeepSeek API Key、OpenAI 兼容 Base URL/API Key/阶段模型、SVN 用户名/密码、输出目录、默认 SVN 预置项目

Git 仓库支持说明

  • 一个 Git 地址即一个项目（与 SVN 语义一致），在「仓库管理」新增仓库时选择类型 Git。
  • Git 抓取基于 JGit（纯 Java），HTTPS 使用「用户名 + Token」，SSH 使用预设中保存的私钥（加密存储）。
  • 首次抓取会 mirror 克隆到 java.io.tmpdir/svnlog-git-cache/<presetId>/（首次较慢），后续增量 fetch。
  • Git 报告显示提交短 hash（如 4fed870），AI 分析与 Excel 汇总逻辑与 SVN 一致，SVN + Git 报告可混合合并为整体工作量统计。
  • SSH 主机密钥默认严格校验（读取 ~/.ssh/known_hosts）；内网可显式开启信任任意主机：
    • SVN_LOG_TOOL_ACCEPT_ANY_SSH_HOST=true 或 -Dsvnlog.git.acceptAnySshHost=true

输出目录

  • 默认输出目录：outputs/
  • Markdown 输出：outputs/md/*.md
  • Excel 输出：outputs/excel/*.xlsx
  • 任务持久化：outputs/task-history.json（重启后可恢复历史）
  • 设置页保存 outputDir 时会自动创建不存在的目录；如果目标路径已被普通文件占用，或当前运行用户对该目录无写权限，PUT /api/settings 会明确返回失败。
  • 如果本机已有 outputs/ 但属主或权限异常，可手动修复为当前用户可写后再保存设置，例如调整目录属主或写权限。

AI 提供商设置

  • DeepSeek：沿用现有两阶段分析链路，读取 DeepSeek API Key
  • OpenAI兼容：使用 baseURL + apiKey + stage1Model + stage2Model 调用兼容 /chat/completions 接口
  • OpenAI 兼容默认值：
    • baseURL=http://127.0.0.1:5001/v1
    • stage1Model=deepseek-v4-flash
    • stage2Model=deepseek-v4-pro

DeepSeek API Key 读取优先级

  1. AI 分析请求中的临时 apiKey
  2. 设置页保存的运行时 apiKey
  3. 环境变量 DEEPSEEK_API_KEY

建议在生产环境优先使用环境变量，避免敏感信息暴露。

SVN 凭据读取优先级

  1. 单次请求显式传入的 username/password（兼容旧接口）
  2. 预设凭据
  3. 全局设置保存的运行时 svnUsername/svnPassword
  4. 环境变量 SVN_USERNAME / SVN_PASSWORD

GET /api/settings 不会回显 openaiApiKey 或 svnPassword 明文，前端通过 openaiApiKeyConfigured 和 svnCredentialsConfigured 展示配置状态。

安全与兼容配置

  • SVN 密码加密密钥不再写死在源码中：
    • 默认生成到 outputs/.svn-log-tool.key
    • 可用 SVN_LOG_TOOL_CRYPTO_KEY 或 -Dsvnlog.crypto.key=... 指定 Base64 AES 密钥
    • 可用 SVN_LOG_TOOL_CRYPTO_KEY_FILE 或 -Dsvnlog.crypto.keyFile=... 指定密钥文件
    • 旧版本固定密钥加密的历史配置需要先用显式密钥启动并重新保存配置完成迁移
  • HTTPS/SVN 默认只启用 TLS 1.2，并保留系统默认的证书校验。
  • 如必须连接旧内网 SVN，可显式启用兼容开关：
    • SVN_LOG_TOOL_ALLOW_LEGACY_TLS=true 或 -Dsvnlog.svn.allowLegacyTls=true
    • SVN_LOG_TOOL_ALLOW_INSECURE_SSL=true 或 -Dsvnlog.svn.allowInsecureSsl=true
  • 异步任务线程数可配置：
    • SVN_LOG_TOOL_TASK_THREADS=16 或 -Dsvnlog.task.threads=16
    • 未配置时默认取 max(8, CPU核数*2)。

前端构建配置

  • VITE_API_BASE_URL：覆盖前端 API Base URL，默认使用同源 /api。
  • VITE_DASHBOARD_POLL_INTERVAL_MS：工作台轮询间隔，默认 8000，最小 3000。

SVN 预设来源与调用方式

  • SVN 地址统一通过仓库管理页维护，并持久化到 outputs/repository-configs.json 文件中。
  • 前端不再传 SVN URL，业务接口统一传 presetId，后端按 presetId 解析地址。
  • GET /api/svn/presets 仅返回 id 与 name（不返回 url）。

主要 API

  • POST /api/svn/test-connection
  • POST /api/svn/fetch
  • POST /api/svn/version-range：按 rangeType=date|week|month 查询版本范围；旧的 year/month 月份请求仍兼容
  • GET /api/svn/presets
  • POST /api/git/test-connection
  • POST /api/git/fetch：按 rangeType=date|week|month + 时间参数直接抓取（Git 无版本号）
  • POST /api/git/version-range：返回 commitCount 与首尾提交 hash
  • GET /api/git/presets
  • POST /api/ai/analyze
  • GET /api/tasks
  • GET /api/tasks/query?status=&type=&keyword=&page=1&size=10
  • GET /api/tasks/{taskId}
  • GET /api/tasks/{taskId}/stream（SSE 实时输出）
  • POST /api/tasks/{taskId}/cancel
  • GET /api/health
  • GET /api/health/details
  • GET /api/files
  • GET /api/files/download?path=...
  • GET /api/settings
  • PUT /api/settings

验证建议

至少执行：

mvn clean compile

如需验证完整流程：

  1. 启动 Web 服务
  2. 在「SVN 日志抓取」创建任务并生成 .md
  3. 在「AI 工作量分析」选择 .md 并生成 .xlsx
  4. 在「任务历史」中下载产物并核验内容

AI 输入校验

为避免误操作和资源滥用，AI 分析接口增加输入约束：

  • 一次最多分析 20 个文件
  • 仅允许 .md 文件
  • 单文件大小不超过 2MB
Reference in New Issue View Git Blame Copy Permalink