ShortLinker v0.5.2

🎉 Release Highlights

v0.5.2 安全修复版本！ 修复 3 个依赖安全漏洞并升级依赖版本：

• 安全修复 - 修复 aws-lc-sys 两个 High 级别漏洞和 rustls-webpki 一个 Medium 级别漏洞
• 依赖升级 - 升级 moka、redis、ureq 等核心依赖至最新版本

Security

• aws-lc-sys 0.38.0 → 0.39.0 - 修复两个 High 级别漏洞
  • CRL Distribution Point Scope Check Logic Error（GHSA #20）
  • X.509 Name Constraints Bypass via Wildcard/Unicode CN（GHSA #19）
• rustls-webpki 0.103.9 → 0.103.10 - 修复一个 Medium 级别漏洞
  • Certificate revocation enforcement bug（GHSA #21）

Dependencies

• 升级 moka 0.12.14 → 0.12.15
• 升级 redis 1.0.5 → 1.1.0，新增 async-lock 依赖
• 升级 ureq 3.2.0 → 3.3.0，替换 utf-8 为 utf8-zero
• 升级 aws-lc-rs 1.16.1 → 1.16.2
• 升级其他间接依赖：arc-swap, borsh, euclid, itoa, zerocopy, zune-jpeg

CI/CD

• 升级 GitHub Actions：actions/checkout v4 → v6，actions/setup-node v4 → v6，actions/upload-artifact v4 → v7
• VitePress 文档构建 Node.js 版本 22 → 24

---

统计数据：

• 7 files changed, 57 insertions(+), 55 deletions(-)
• 2 commits

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.2_linux_x86_64
Linux	ARM64	shortlinker_v0.5.2_linux_aarch64
Windows	x86_64	shortlinker_v0.5.2_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.2_macos_x86_64
macOS	ARM64	shortlinker_v0.5.2_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.2.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.1

🎉 Release Highlights

v0.5.1 维护版本发布！ 这是一个重要的架构优化与稳定性提升版本：

• 客户端层架构 - 引入 client/ 模块，实现 IPC 优先 + Service 降级模式，提升 CLI/TUI 的可靠性
• IPC 配置管理 - 支持通过 IPC 进行配置查询、修改、重置和批量导入
• 流式导入/导出 - 支持进度报告和游标分页，大幅降低内存占用
• 数值溢出修复 - 修复 Analytics 模块多处 i64 溢出问题，提升高并发稳定性
• TUI 功能增强 - 分页加载、虚拟滚动、系统操作面板，支持大数据量场景
• 高性能批量导入 - 使用 Bloom filter 预筛选 + batch 操作，大幅提升导入性能

Added

• 客户端层架构 - 新增 src/client/ 模块（1303 行）
  • LinkClient: 链接操作客户端，支持 IPC 优先、服务降级
  • ConfigClient: 配置管理客户端
  • SystemClient: 系统操作客户端
  • ServiceContext: 统一服务上下文管理
  • 支持 ServerNotRunning 自动降级到本地服务，其他 IPC 错误不降级（避免双写）
• IPC 配置管理命令
  • ConfigList { category }: 列出配置（支持分类过滤）
  • ConfigGet { key }: 获取单个配置
  • ConfigSet { key, value }: 设置配置值
  • ConfigReset { key }: 重置为默认值
  • ConfigImport { configs }: 批量导入配置
• IPC 批量删除 - BatchDeleteLinks { codes } 命令
• 流式导入/导出
  • ImportLinks 新增 stream_progress: bool 字段，支持进度报告
  • ImportProgress 响应类型：{ phase, processed, total, success, skipped, failed }
  • ExportChunk 和 ExportDone 响应类型，支持流式导出
  • LinkService::export_links_stream(): 游标分页流式导出
• 高性能批量导入
  • LinkService::import_links_batch(): 使用 Bloom filter 预筛选 + batch_check_codes_exist 精确查询 + batch_set 批量写入
  • LinkService::import_links_batch_chunked(): 支持分块写入和进度回调
  • 新增 DTO：ImportLinkItemRich、ImportBatchResult、ImportBatchFailedItem
• TUI 功能增强
  • 分页加载和虚拟滚动（+545 行）
  • 数据库搜索支持
  • 系统操作面板（+217 行）：服务器状态查看、运行时配置编辑、密码重置
  • 配置管理 UI（config_list.rs, config_edit.rs, config_reset_confirm.rs）
  • 导入模式选择 UI（import_mode.rs）
• 导入错误处理增强
  • ImportErrorData 新增 error_code: Option<String> 字段，支持结构化错误码
  • 行号追踪：ImportLinkItemRich.row_num 透传到 ImportBatchFailedItem.row_num
• 测试覆盖 - 新增 821 行客户端层集成测试（tests/client_tests.rs）

Fixed

• 数值溢出修复
  • analytics/manager.rs: 修复 i64 溢出问题，改用 try_from 和 unwrap_or 替换手动类型转换
  • 提升高并发场景容量（crossbeam channel 容量从 10000 增至 50000）
  • analytics/hourly_writer.rs 和 analytics/rollup.rs: 修复多处边界条件与逻辑缺陷
• IPC 流异常关闭处理
  • ClickManager 新增 shutdown 信号机制（tokio::sync::watch::channel）
  • start_background_task() 使用 tokio::select! 监听 shutdown 信号
  • process_raw_events() 在 shutdown 时 drain 剩余事件，避免丢失详细点击信息
• 导入失败项行号处理 - 修复 CSV 导入时行号映射不准确的问题
• 敏感配置显示 - 修复导入时敏感配置（如密码）的显示问题
• 多处潜在崩溃修复 - analytics, tui, services 模块的边界条件和逻辑错误

Changed

• IPC DTO 简化
  • 删除 ShortLinkData 中间层，IPC 直接传输 ShortLink
  • 消除 to_link_data() 和 link_data_to_short_link() 转换函数
  • 消除 i64 ↔ usize、String ↔ DateTime 胶水代码
  • 删除 ipc/types.rs 中 300+ 行纯序列化测试
• IPC Handler 守卫函数提取
  • 提取 get_link_service() 和 get_config_service() 消除 13 处重复守卫
  • 提取 validate_editable_key() 消除配置操作的重复 def 检查
  • 新增 IpcCommand::name() 方法，日志中隐藏敏感字段
• Admin API 统一访问模式 - 所有 admin API 必须通过 service 层访问（已文档化在 services/mod.rs）
• 导入验证逻辑统一 - 提取 validate_import_rows() 函数，消除重复的冲突检测逻辑
• Analytics 性能优化 - 使用 try_from 替换手动类型转换，提升高并发容量

Deprecated

以下 API 标记为废弃，将在 v0.6.0 删除：

• ImportLinkItem → 使用 ImportLinkItemRich
• ImportResult → 使用 ImportBatchResult
• ImportError → 使用 ImportBatchFailedItem
• LinkService::import_links() → 使用 import_links_batch()
• LinkService::export_links() → 使用 export_links_stream()
• LinkService::export_click_logs() 标记废弃

Dependencies

升级全量依赖至最新版本：

• actix-web: 4.12 → 4.13
• rand: 0.9.2 → 0.10.0
• chrono: 0.4.43 → 0.4.44
• tokio: 1.49.0 → 1.50.0
• tracing-subscriber: 0.3.22 → 0.3.23
• moka: 0.12.13 → 0.12.14
• futures-util: 0.3.31 → 0.3.32
• once_cell: 1.21.3 → 1.21.4
• anyhow: 1.0.101 → 1.0.102
• uuid: 1.20 → 1.22
• redis: 1.0.3 → 1.0.5
• rustls: 0.23.36 → 0.23.37
• toml: 0.9 → 1.0
• sea-orm: 2.0.0-rc.31 → 2.0.0-rc.37
• strum: 0.27 → 0.28

删除：tokio-test 依赖

Documentation

• 补充批量操作与 TUI 分页说明，优化类型转换与资源管理
• 修正每日汇总数据保留配置的说明

---

统计数据：

• 104 files changed, 8672 insertions(+), 2806 deletions(-)
• 25 commits (20 功能/修复/重构提交)
• 新增 1303 行客户端层代码
• 新增 821 行测试代码

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.1_linux_x86_64
Linux	ARM64	shortlinker_v0.5.1_linux_aarch64
Windows	x86_64	shortlinker_v0.5.1_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.1_macos_x86_64
macOS	ARM64	shortlinker_v0.5.1_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.1.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0

🎉 Release Highlights

v0.5.0 正式版发布！ 这是一个里程碑版本，经过 6 个 alpha、2 个 beta、1 个 rc 的迭代打磨，带来了全面的功能增强与架构优化：

• 详细点击分析系统 - GeoIP 地理位置、设备指纹、UTM 来源追踪，支持多维度数据分析
• 高性能异步架构 - Analytics 事件队列、游标分页导出、缓存原子重建，大幅提升性能
• Prometheus 指标导出 - 18 项可观测性指标，涵盖 HTTP、数据库、缓存等维度
• 运行时配置系统 - 23 项配置支持热更新，无需重启即可调整行为
• 测试覆盖大幅提升 - 新增 10+ 集成测试模块，覆盖 API、Analytics、IPC、中间件等核心功能

Added (since v0.4.3)

• 详细点击分析 - 新增 click_logs 表和多维度统计
  • GeoIP 地理位置解析（国家、城市、经纬度）
  • 设备指纹分析（浏览器、操作系统、设备类型、是否机器人）
  • UTM 来源追踪（utm_source / ref:domain / direct）
  • 全局天级汇总统计（click_stats_global_daily 表）
• 点击日志采样控制 - 新增运行时配置
  • analytics.sample_rate - 采样率（0.0-1.0）
  • analytics.max_log_rows - 最大行数限制
  • analytics.max_rows_action - 超限行为（cleanup/stop）
• Prometheus 指标系统 - 18 项指标，/health/metrics 端点
  • HTTP 请求延迟直方图、活跃连接数
  • 数据库查询延迟、缓存命中率
  • 重定向状态码统计、点击缓冲区大小
  • 系统运行时间、进程内存、CPU 时间
• 配置 Action API - 支持通过 API 执行配置操作
  • POST /admin/v1/config/{key}/action - 执行并返回结果
  • POST /admin/v1/config/{key}/execute-and-save - 执行并保存
  • 目前支持 api.jwt_secret 的 generate_token action
• IPC 配置化 - 新增 [ipc] 配置段
  • 自定义 socket 路径、超时参数、消息大小限制
  • CLI 全局 --socket 参数覆盖配置
• Bloom Filter 定时重建 - cache.bloom_rebuild_interval 配置（默认 4 小时）
• 数据库索引优化 - 新增 4 个复合索引优化分析查询性能
• 集成测试套件 - 新增 10+ 测试模块（+5283 行）
  • Admin API、Analytics、Auth、CORS、IPC、Metrics、中间件等

Improved (since v0.4.3)

• Analytics 异步处理 - 使用 crossbeam-channel 将详细日志处理移出热路径
• 缓存原子重建 - Bloom Filter 重建期间零空窗期，增量 buffer 防止并发写入丢失
• 链接导出游标分页 - 使用 short_code 游标替代 OFFSET，大数据量性能提升 10-100 倍
• 小时汇总批量 Upsert - 单次数据库交互完成所有汇总写入
• Moka 缓存 TTL 抖动 - ±10% 随机抖动避免缓存雪崩
• 数据库连接池优化 - SQLite 最大连接数 5→10，通用后端 pool_size 10→20
• 分析查询内存保护 - 时间范围限制 90 天，聚合 key 限制 1000
• IPC 服务检测增强 - Ping 验证替代文件存在检查，1 秒超时避免僵死进程
• 重定向性能优化 - UTM 解析、GeoIP 查询全部移到后台，不阻塞 307 响应
• Windows 命名管道安全 - 迁移至 windows-sys，增强安全描述符配置

Refactored (since v0.4.3)

• Metrics 系统统一 - 移除大量条件编译，使用 MetricsRecorder trait 注入
  • 新增 metrics_core.rs 模块，定义 trait 和 NoopMetrics
  • 所有模块无条件接受 Arc<dyn MetricsRecorder>
• 配置系统重构 - 支持环境变量覆盖和运行时热更新
  • 23 项运行时配置，涵盖认证、Cookie、功能开关、路由、CORS、追踪等
  • 配置元信息系统（definitions.rs）为 Admin UI 提供 schema
• 密码处理逻辑分离 - 区分用户输入与导入数据
  • process_new_password() / process_update_password() 始终哈希
  • 新增 process_imported_password() 用于 CSV 导入
• TUI 状态管理 - 引入 FormState 状态机，表单验证逻辑统一
• Analytics 模块 - 重构为统一业务逻辑层，支持流式 CSV 导出
• 移除 JSON 导入支持 - 统一使用 CSV 格式
• 缓存初始化简化 - rebuild_all() 内部自行从数据库流式加载

Fixed (since v0.4.3)

• 点击刷盘 SQLite 变量限制 - 分批处理，每批最多 400 条记录
• 关闭时刷盘重试 - 增加 3 次重试机制，每次 30 秒超时
• 重试逻辑增强 - 新增死锁和锁超时检测（MySQL/PostgreSQL/SQLite）

Dependencies

• 新增 crossbeam-channel 0.5 - Analytics 事件队列
• 新增 prometheus 0.14 - 指标导出（可选 feature）
• 新增 sysinfo 0.38 - 系统指标收集（可选 feature）
• 新增 maxminddb 0.27 - GeoIP 解析
• 新增 ureq 3.2.0 - HTTP 客户端（替换 reqwest）
• 新增 woothee 0.13 - User-Agent 解析
• 新增 urlencoding 2.1.3 - URL 参数解码
• 升级 rand 0.9.2 → 0.10.0
• 升级 sea-orm 2.0.0-rc.30 → 2.0.0-rc.31
• Windows: 迁移至 windows-sys 0.61（移除 winapi）

Docs

• 文档结构重组 - 配置、部署、API 文档拆分为细粒度文件
  • 配置指南：启动配置、运行时配置、安全实践、示例
  • 部署指南：Docker/Proxy/Systemd 各拆分为快速入门和运维文档
  • API 文档：Admin/Health 各拆分为端点详解
• 新增事件系统文档（为插件化架构做准备）
• 新增 Prometheus 指标文档
• 新增 Analytics API 文档
• 移除 v0.3.x 版本警告通知

Breaking Changes

• Admin Token 默认值变更 - 默认为空字符串（原来自动生成），首次启动需运行 reset-password 手动设置
• CLI 命令变更 - generate-config → config generate
• 数据库 Schema 变更 - 新增多个表和字段（自动迁移）
  • 新增表：click_logs、user_agents、click_stats_global_daily
  • 新增字段：click_stats_hourly.source_counts、click_stats_daily.top_sources
  • 删除字段：click_logs.user_agent（改为 hash 引用）
• API 响应变化 - /admin/v1/stats 的 referrers 现在返回 source（utm_source / ref:{domain} / direct）
• Metrics Feature API 签名变化 - SeaOrmStorage::new、CompositeCache::create、ClickManager::new 需要传入 metrics 参数
• JWT 配置需重启 - api.jwt_secret、api.access_token_minutes、api.refresh_token_days 现在需要重启生效
• 缓存 API 变更 - reconfigure() 和 load_bloom() 合并为 rebuild_all()
• 密码处理 API 变更 - process_new_password() 不再接受预哈希值，导入场景使用 process_imported_password()

Migration Notes

⚠️ 从 v0.4.x 升级注意事项：

1. 数据库迁移 - 自动运行，新增多个表和索引（首次启动可能需要几秒）
2. Admin Token - 默认为空，需运行 shortlinker reset-password 设置密码
3. CLI 命令 - generate-config 改为 config generate
4. 配置文件 - 建议重新生成配置文件查看新增配置项

   shortlinker config generate --force

5. 新增配置项（可选）：
   • cache.bloom_rebuild_interval - Bloom Filter 重建间隔（秒，默认 14400）
   • analytics.sample_rate - 点击日志采样率（默认 1.0）
   • analytics.max_log_rows - 最大日志行数（默认 0 = 无限制）
   • [ipc] 配置段 - IPC 服务器设置
6. Docker 用户 - 如需 Prometheus 指标，使用 latest-metrics 标签

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-rc.1

🎉 Release Highlights

v0.5.0-rc.1 是一次架构优化与可靠性增强版本，主要亮点：

• 全局天级点击统计汇总 - 新增 click_stats_global_daily 表，支持全局维度的天级趋势分析
• 缓存原子重建机制 - Bloom Filter 重建期间零空窗期，增量 buffer 防止并发写入丢失
• Metrics 系统统一 - 移除大量条件编译，统一使用 trait 注入，代码更清晰
• 配置 Action API - 支持通过 API 生成 JWT Secret 等敏感配置

Added

• 全局天级点击统计汇总 - 新增 click_stats_global_daily 表
  • 每天一条全局记录：总点击数、唯一链接数、Top 10 referrers/countries/sources
  • 在 hourly → daily rollup 时自动计算，支持覆盖式 upsert（幂等性）
  • 过期数据随 daily retention 策略自动清理
• Bloom Filter 定时重建任务 - 新增 cache.bloom_rebuild_interval 配置项（默认 4 小时，0 = 禁用）
  • 后台定期触发缓存重建，保持 Bloom Filter 与数据库同步
• 缓存原子重建机制 - 新增 rebuild_all() 方法
  • 在锁外构建新 Bloom Filter，然后原子交换，消除更新空窗期
  • 增量 buffer 捕获重建期间的并发写入，最后一起合入新 Bloom
  • 分段预留策略：小规模 50%、中等 20%、大规模 10%
• 配置 Action API - 新增两个端点
  • POST /admin/v1/config/{key}/action - 执行 action 并返回生成的值
  • POST /admin/v1/config/{key}/execute-and-save - 执行 action 并保存（不返回敏感值）
  • 目前支持 GenerateToken action（生成 32 字节 hex token），应用于 api.jwt_secret
• 分页 IPC 导出 - CLI 导出改为分页请求（每页 100 条），避免 IPC 消息大小限制

Improved

• IPC 服务检测增强 - 发送 Ping 命令验证服务器实际响应，1 秒超时避免僵死进程阻塞
• IP 解析逻辑简化 - 使用 let-else 模式减少嵌套，直接 parse 为 IpAddr

Refactored

• Metrics 系统统一 - 移除大量 #[cfg(feature = "metrics")] 条件编译
  • 新增 metrics_core.rs 模块，定义 MetricsRecorder trait 和 NoopMetrics
  • 所有模块无条件接受 Arc<dyn MetricsRecorder>，禁用时自动注入 NoopMetrics
• 密码处理逻辑分离 - 区分用户输入与导入数据
  • process_new_password() / process_update_password() 始终哈希，不接受预哈希值
  • 新增 process_imported_password() 用于 CSV 导入（已哈希则保留，明文则哈希）
• 移除 JSON 导入支持 - 统一使用 CSV 格式，移除已弃用的 JSON 导入逻辑
• 缓存初始化简化 - 原来需要外部加载短码列表再传入，现在 rebuild_all() 内部自行从数据库流式加载
• 存储后端统一 - 移除 metrics 条件编译的 new() 方法分支，统一为单一构造函数

Docs

• 大规模更新中英文文档，涵盖安全实践、配置说明及 TUI 功能
• 移除 v0.3.x 版本警告通知
• 新增配置 Action API 文档

Breaking Changes

• Admin Token 默认值变更 - 默认为空字符串（原来自动生成），首次启动需运行 reset-password 手动设置
• 缓存 API 变更 - reconfigure() 和 load_bloom() 合并为 rebuild_all()
• 密码处理 API 变更 - process_new_password() 不再接受预哈希值，导入场景使用 process_imported_password()

Migration Notes

⚠️ 从 v0.5.0-beta.2 升级注意事项：

1. 数据库 - 自动运行迁移，新增 click_stats_global_daily 表
2. Admin Token - 默认为空，需运行 shortlinker reset-password 设置密码
3. 新增配置项 - cache.bloom_rebuild_interval（秒，默认 14400，0 = 禁用）

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-rc.1_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-rc.1_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-rc.1_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-rc.1_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-rc.1_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-rc.1.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-beta.2

🎉 Release Highlights

v0.5.0-beta.2 是一次性能优化与架构改进版本，主要亮点：

• Analytics 异步处理架构 - 使用 crossbeam-channel 将详细日志处理从热路径移出，减少重定向延迟
• 点击日志采样率控制 - 新增 analytics.sample_rate 和 analytics.max_log_rows 配置，按需控制日志量
• 数据库索引优化 - 新增 4 个索引优化分析查询性能
• 链接导出游标分页 - 大数据量导出性能提升 10-100 倍

Added

• 点击日志采样率控制 - 新增运行时配置
  • analytics.sample_rate (float, 默认 1.0) - 点击日志采样率，支持 0.0-1.0
  • analytics.max_log_rows (int, 默认 0) - click_logs 表最大行数限制，0 表示无限制
  • analytics.max_rows_action (enum, cleanup/stop) - 超过限制时的行为
• 数据库索引优化 - 新增两个迁移文件
  • idx_click_logs_source_time: (source, clicked_at) 复合索引
  • idx_click_logs_geo: (country, city, clicked_at) 复合索引
  • idx_stats_hourly_code: click_stats_hourly.short_code 索引
  • idx_user_agents_is_bot: user_agents.is_bot 索引
• 链接导出游标分页 - 使用 short_code 作为游标替代 OFFSET 分页
• 新增 Metrics - shortlinker_clicks_channel_dropped 统计详细点击事件丢弃次数

Improved

• Analytics 异步处理 - 引入 crossbeam-channel 事件队列
  • 热路径只发送原始数据到 channel（无 spawn 开销）
  • 单独的 event_processor 协程消费 channel，批量处理详细日志
• 小时汇总批量 Upsert - 使用 ON CONFLICT DO UPDATE 单次数据库交互完成所有汇总写入
• Moka 缓存 TTL 抖动 - 为所有 TTL 添加 ±10% 随机抖动，避免缓存雪崩
• Bloom Filter 预留策略 - 分段预留（小规模 50%，中等 20%，大规模 10%）
• 数据库连接池优化 - SQLite 最大连接数 5→10，通用后端 pool_size 10→20
• 分析查询内存保护 - 时间范围限制 90 天，聚合 key 限制 1000

Refactored

• Metrics 依赖注入 - 引入 MetricsRecorder trait 解耦指标收集
  • 测试时可使用 NoopMetrics
  • 模块不再依赖全局单例
• 日志级别调整 - 多处 warn! 调整为 info!，减少正常运行时的 WARNING 噪音
• 重试逻辑增强 - 新增死锁和锁超时检测（MySQL/PostgreSQL/SQLite）

Fixed

• 点击刷盘 SQLite 变量限制 - 分批处理，每批最多 400 条记录
• 关闭时刷盘重试 - 增加 3 次重试机制，每次 30 秒超时

Dependencies

• 新增 crossbeam-channel 0.5 用于 Analytics 事件队列

Docs

• 更新配置文档，新增采样率相关配置说明
• Cloudflare Worker 文档状态调整为"实验中"
• Docker 文档示例版本号改为占位符

Breaking Changes

• Metrics Feature API 签名变化 - SeaOrmStorage::new、CompositeCache::create、ClickManager::new 需要传入 metrics 参数
• JWT 配置需重启 - api.jwt_secret、api.access_token_minutes、api.refresh_token_days 现在需要重启生效

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-beta.2_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-beta.2_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-beta.2_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-beta.2_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-beta.2_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-beta.2.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-beta.1

本版本存在严重性能问题，请谨慎使用

🎉 Release Highlights

v0.5.0-beta.1 是一次功能增强与架构优化版本，主要亮点：

• UTM 来源追踪 - 自动从 utm_source 参数或 Referer 推导流量来源，异步处理不阻塞重定向
• IPC 配置化 - 新增 [ipc] 配置段，支持自定义 socket 路径、超时等参数
• TUI 状态管理重构 - 引入 FormState 状态机，表单验证逻辑统一
• 文档结构重组 - 配置、部署、API 文档拆分为细粒度小文件

Added

• UTM 来源追踪系统 - 新增 source 字段记录流量来源
  • 推导逻辑：优先 utm_source 参数 → Referer 域名（ref:domain）→ direct
  • 数据库迁移：click_logs.source、click_stats_hourly.source_counts、click_stats_daily.top_sources
  • 异步处理：URL 解析、域名提取不阻塞 307 响应
• IPC 配置段 - 新增 [ipc] 配置支持
  • enabled：启用/禁用 IPC 服务器
  • socket_path：自定义 socket 路径
  • timeout/reload_timeout/bulk_timeout：各类操作超时配置
  • max_message_size：最大消息大小（默认 64KB）
• CLI 全局参数 - --socket 参数覆盖配置文件中的 socket 路径

Changed

• CLI 命令重构 - generate-config 改为 config generate，统一子命令风格
  • 新增 --force 参数强制覆盖现有配置文件

Improved

• 重定向性能优化 - UTM 解析、GeoIP 查询全部移到后台 spawn，不阻塞 307 响应
• 存储空间优化 - 删除 click_logs.user_agent 列，只保留 hash 引用

Refactored

• TUI 状态管理 - 引入 FormState 结构体和 EditingField 枚举，取代零散的输入状态字段
  • 表单验证逻辑统一到 validation.rs
  • UI 组件（add_link.rs、edit_link.rs 等）大幅简化
• Analytics 模块 - Rollup 汇总逻辑新增 source_counts 处理

Dependencies

• 升级 anyhow 1.0.100 → 1.0.101
• 新增 urlencoding 2.1.3（URL 参数解码）

Docs

• 文档结构重组 - 配置、部署、API 文档拆分为细粒度文件
  • 配置指南：startup.md、runtime.md、security.md、examples.md
  • 部署指南：Docker/Proxy/Systemd 各拆分为快速入门和运维文档
  • API 文档：Admin/Health 各拆分为端点详解
• 新增事件系统文档（events/README.md）

Breaking Changes

• CLI 命令变更 - generate-config → config generate
• 数据库 Schema 变更 - 新增 source 相关字段，删除 click_logs.user_agent 列
• API 响应变化 - /admin/v1/stats 的 referrers 现在返回 source（utm_source / ref:{domain} / direct）

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-beta.1_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-beta.1_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-beta.1_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-beta.1_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-beta.1_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-beta.1.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-alpha.6

🎉 Release Highlights

v0.5.0-alpha.6 是一次可观测性增强版本，主要亮点：

• Prometheus 指标系统 - 全新 18 项指标，涵盖 HTTP、数据库、缓存、重定向、认证等维度
• Docker 多变体构建 - 标准版和 metrics 版分离，按需选择
• 事件系统文档重构 - 为插件化架构做准备，引入 trait-based Event 系统设计

Added

• Prometheus 指标导出 - 新增 /health/metrics 端点，导出 Prometheus 文本格式指标
  • HTTP：请求延迟直方图、请求计数、活跃连接数
  • 数据库：查询延迟、查询计数
  • 缓存：操作延迟、条目数、命中/未命中计数
  • 重定向：按状态码（307/404/500）统计
  • 点击：缓冲区大小、刷盘计数（按触发方式）
  • 认证：鉴权失败计数
  • Bloom Filter：假阳性计数
  • 系统：运行时间、进程内存、CPU 时间、构建信息
• TimingMiddleware - 自动记录所有 HTTP 请求的延迟和计数，使用 Drop Guard 确保活跃连接数准确
• 系统指标收集器 - 使用 sysinfo 库每 15 秒更新进程内存和 CPU 时间
• 指标辅助宏 - observe_duration!、inc_counter!、set_gauge! 等宏减少样板代码
• Docker metrics 变体 - 新增 latest-metrics、stable-metrics、edge-metrics 等镜像标签

Improved

• API 响应格式统一 - 所有端点响应统一为 {code, message, data} 格式
• 健康检查增强 - 新增缓存状态信息和 uptime 指标
• ObjectCache trait - 新增 entry_count() 方法用于指标收集

Refactored

• 指标记录优化 - 移除不必要的字符串克隆，端点分类返回 &'static str 避免堆分配
• 事件系统设计 - 文档重构为 trait-based Event 系统，支持事件取消和优先级机制

Dependencies

• 添加 prometheus 0.14（可选，metrics feature）
• 添加 sysinfo 0.38（可选，metrics feature）
• 升级 ureq 3.1.4 → 3.2.0
• 升级 time 0.3.45 → 0.3.47
• 升级 darling 0.20.11 → 0.23.0

CI/CD

• Docker 多变体构建 - 构建矩阵支持 default 和 metrics 两个变体
• 镜像标签策略 - 新增 edge/stable 标签，metrics 版添加 -metrics 后缀
• VitePress 文档 - 新增标签触发构建

Docs

• 新增 /health/metrics 端点文档
• 新增 Docker metrics 版部署说明
• 重构事件系统文档，引入插件化架构设计
• 更新 API 响应格式说明

Breaking Changes

• 最低 Rust 版本 - 要求 Rust 1.88+
• API 响应格式 - 从 {code, data} 变更为 {code, message, data}

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-alpha.6_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-alpha.6_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-alpha.6_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-alpha.6_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-alpha.6_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-alpha.6.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-alpha.5

🎉 Release Highlights

v0.5.0-alpha.5 是一次代码质量和安全性提升版本，主要亮点：

• 请求 ID 中间件 - 每个请求分配唯一 UUID，注入日志 span 和响应头，便于追踪调试
• 缓存健康检查 - 健康检查端点新增缓存状态信息（类型、Bloom filter、Negative cache 状态）
• 批量操作安全增强 - 新增 5000 条批量大小限制和 10MB 导入文件限制
• 关机超时机制 - 优雅关闭增加 30 秒总超时保护，防止关闭卡死

Added

• Request ID 中间件 - 为每个请求生成 UUID v4，注入 tracing span 和 X-Request-ID 响应头
• 缓存健康检查 - /health 端点现在返回缓存状态（类型、Bloom filter、Negative cache）
• Refresh Token 限流 - 每 10 秒 1 次请求，突发最多 10 次，防止滥用
• 批量操作大小限制 - 批量创建/更新/删除最多 5000 条
• 导入文件大小限制 - CSV 导入最大 10MB
• 新增错误码 - BatchSizeTooLarge、FileTooLarge、InvalidDateFormat、LinkInvalidCode、LinkReservedCode

Improved

• 关机流程 - 增加超时机制（30 秒总超时，单任务 10 秒），超时强制退出防止卡死
• 日期参数验证 - created_after/created_before 参数无效时返回明确错误信息
• JWT Service 缓存 - 使用 OnceLock 缓存实例，避免每次请求重复创建
• 登录日志 - 登录成功/失败日志包含客户端 IP
• Bloom filter 初始容量 - 改为 100（启动时 reconfigure 会用实际数量替换），减少初始内存占用

Security

• Health Token 常量时间比较 - 使用 subtle::ConstantTimeEq 防止时序攻击
• Admin Token 生成增强 - 默认使用加密安全的 OsRng 生成 32 字符令牌

Refactored

• 移除 AdminService 包装层 - 直接使用函数，减少间接调用
• IP 提取逻辑统一 - 登录限流和其他地方共用 utils/ip.rs 中的函数
• 批量操作重构 - 使用 LinkService 统一业务逻辑层
• 小时汇总写入器 - 新增 HourlyRollupWriter 统一 click_sink 和 rollup 的汇总逻辑
• 配置管理代码 - 使用宏简化 get_runtime_config_or_return!() 重复模式
• 前端服务 - 统一 serve_index_html() 逻辑，消除代码重复

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-alpha.5_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-alpha.5_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-alpha.5_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-alpha.5_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-alpha.5_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-alpha.5.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-alpha.4

🎉 Release Highlights

v0.5.0-alpha.4 是一次 Analytics 系统的重大升级，主要亮点：

• 点击数据汇总系统 - 多级汇总架构（小时/天/全局），大数据量查询性能提升 10-100 倍
• UserAgent 去重存储 - xxHash64 去重 + woothee 解析，存储减少 30-70%
• 设备分析 API - 新增浏览器、操作系统、设备类型统计端点
• 自动数据清理 - 可配置的保留策略，防止存储无限增长

Added

• 点击数据汇总系统 - 实时更新的多级汇总架构
  • click_stats_hourly：每个短链接每小时的点击数、来源分布、国家分布
  • click_stats_daily：每个短链接每天的点击数、唯一来源数、唯一国家数
  • click_stats_global_hourly：全局每小时总点击数、活跃链接数
  • 后台任务自动将小时汇总滚动到天汇总
• UserAgent 去重存储系统 - 新增 user_agents 表和 UserAgentStore 服务
  • 使用 xxHash64 生成 16 字符 hex hash 作为唯一标识
  • 使用 woothee 解析浏览器、操作系统、设备类型
  • DashMap/DashSet 高性能并发缓存
  • 后台任务每 30 秒批量写入新 UA
  • 支持历史数据自动迁移和字段回填
• 设备分析 API - 两个新端点
  • GET /admin/v1/analytics/devices - 全局设备分析
  • GET /admin/v1/links/{code}/analytics/devices - 单链接设备分析
  • 返回浏览器、操作系统、设备类型分布和 Bot 占比
• 自动数据清理任务 - 可配置的保留策略
  • 原始点击日志：默认 30 天
  • 小时汇总：默认 7 天
  • 天汇总：默认 365 天
  • 后台任务每 4 小时运行，分批删除避免长事务
• 新增配置项
  • analytics.enable_auto_rollup - 启用自动汇总和清理（默认 true）
  • analytics.hourly_retention_days - 小时汇总保留天数（默认 7）
  • analytics.daily_retention_days - 天汇总保留天数（默认 365）

Improved

• Analytics V2 查询方法 - 从汇总表读取的高性能查询
  • get_trends_v2()、get_link_trends_v2() 等方法提升 10-100 倍性能
  • 游标分页导出替代 OFFSET，大数据量导出性能显著提升
• Click Sink 增强 - 每次 flush 时自动更新汇总表
• 查询表达式统一 - 排序和分组使用统一的表达式克隆，避免字符串表达式

Refactored

• 启动流程重构 - 新增 UserAgentStore 初始化、历史数据迁移、UA 后台任务、数据清理任务
• 日志消息语言统一 - 从中文统一为英文

Dependencies

• 添加 xxhash-rust 用于 UA hash 生成
• 添加 woothee 用于 UA 解析

Docs

• 新增设备分析 API 文档
• 更新配置文档，添加汇总和清理相关配置项说明
• 更新 analytics.log_retention_days 说明（自动清理已实装）

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-alpha.4_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-alpha.4_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-alpha.4_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-alpha.4_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-alpha.4_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-alpha.4.tar.gz

Checksums: checksums.txt

ShortLinker v0.5.0-alpha.3

🎉 Release Highlights

v0.5.0-alpha.3 是一次依赖优化版本，主要亮点：

• HTTP 客户端替换 - 将 reqwest 替换为轻量级的 ureq，显著减少依赖体积
• GeoIP 服务改进 - 改进日志信息，增强错误处理
• Docker 标签策略优化 - alpha/beta/rc 版本不再打 latest 标签

Changed

• HTTP 客户端迁移 - 将 GeoIP 外部 API 调用从 reqwest 迁移到 ureq
  • ureq 是同步轻量级 HTTP 客户端，通过 spawn_blocking 异步执行
  • 移除 hyper、quinn (QUIC)、tower 等重量级依赖，减小编译体积
• Docker 镜像标签策略 - 优化预发布版本的标签行为
  • alpha/beta/rc 版本仅打版本号标签（如 v0.5.0-alpha.3）
  • 正式版本打 latest、stable 和主版本号标签（如 v1）

Improved

• GeoIP 服务日志 - 错误日志中显示完整 URL，便于调试
• GeoIP API 响应处理 - 正确处理 ip-api.com 返回的 status: fail 状态
• 文档版本显示 - VitePress 导航栏动态显示当前版本号

Fixed

• GeoIP API 默认 URL - 增加 status 字段请求参数，确保能检测 API 失败状态

Dependencies

• 替换 reqwest (0.13) 为 ureq (3.1.4)
• 移除 hyper、hyper-util、quinn、tower、tower-http 等间接依赖

Tests

• 新增 4 个 GeoIP 外部 API 测试（标记 #[ignore] 因依赖外部网络）

---

Installation

Homebrew (macOS/Linux)

brew install AptS-1547/tap/shortlinker

Cargo Binstall

cargo binstall shortlinker

Manual Download

Platform	Architecture	Download
Linux	x86_64	shortlinker_v0.5.0-alpha.3_linux_x86_64
Linux	ARM64	shortlinker_v0.5.0-alpha.3_linux_aarch64
Windows	x86_64	shortlinker_v0.5.0-alpha.3_windows_x86_64.exe
macOS	x86_64	shortlinker_v0.5.0-alpha.3_macos_x86_64
macOS	ARM64	shortlinker_v0.5.0-alpha.3_macos_aarch64
Admin Panel	-	shortlinker-admin-panel_v0.5.0-alpha.3.tar.gz

Checksums: checksums.txt