Merge pull request #63 from AptS-1547/develop

Develop & Release 0.4.1

Author: AptS-1547

.github/workflows/rust.yml

@@ -19,12 +19,63 @@ env:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
+
+    - name: Setup Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+
+    - name: Cache cargo registry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-
+
     - name: Build
       run: cargo build --verbose
+
     - name: Run tests
       run: cargo test --verbose
+
+  coverage:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+
+    - name: Cache cargo registry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-
+
+    - name: Install cargo-tarpaulin
+      run: cargo install cargo-tarpaulin
+
+    - name: Generate coverage report
+      run: cargo tarpaulin --out Xml --output-dir coverage
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        files: coverage/cobertura.xml
+        fail_ci_if_error: false
+        verbose: true
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -31,4 +31,5 @@ links.db*
 links.json
 shortlinker.pid
 cargo-flamegraph.trace/
-flamegraph.svg
+flamegraph.svg
+coverage/

CHANGELOG.md

@@ -5,6 +5,85 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.4.1] - 2026-02-01
+
+### 🎉 Release Highlights
+
+v0.4.1 是一次重要的安全与性能优化版本，主要亮点：
+
+- **CSRF 防护** - 双令牌模式的 CSRF 中间件，防止跨站请求伪造攻击
+- **流式 CSV 导出** - 支持大规模数据导出，内存占用从 O(N) 降至 O(batch_size)
+- **登录限流安全增强** - 可信代理配置，防止 IP 伪造绕过限流
+- **CSV 导入性能优化** - Bloom Filter 预筛选 + 批量查询，显著提升冲突检测性能
+- **全面的测试覆盖** - 新增 8 个基准测试和覆盖 22 个模块的单元测试
+
+### Added
+- **CSRF 防护中间件** - 双令牌模式，验证 `X-CSRF-Token` header 与 Cookie 匹配
+  - 使用 `subtle::ConstantTimeEq` 进行常量时间比较，防止时序攻击
+  - 安全方法（GET/HEAD/OPTIONS）和 Bearer Token 认证自动跳过
+  - 认证端点（login/refresh/logout）自动跳过 CSRF 验证
+- **流式 CSV 导出** - 分批次流式导出（每批 10,000 条），支持 `Transfer-Encoding: chunked`
+  - 使用 `spawn_blocking` 将 CSV 序列化移到独立线程池，避免阻塞 worker 线程
+  - 内存占用优化：导出 100 万条链接内存占用从 O(N) 降至 O(1000)
+- **可信代理配置** - 新增 `api.trusted_proxies` 配置项（支持 IP 和 CIDR 格式）
+  - 登录限流 key 优先使用连接 IP（不可伪造），仅可信代理时使用 `X-Forwarded-For`
+  - 支持 IPv4/IPv6 CIDR 匹配（如 `192.168.1.0/24`）
+- **批量短码存在性检查 API** - `batch_check_codes_exist()` 方法，支持分批查询（每批 500 个）
+- **API 常量模块** - 硬编码 Cookie 名称（`shortlinker_access`, `shortlinker_refresh`, `csrf_token`）
+- **全面的基准测试套件** - 新增 8 个基准测试，覆盖缓存、IPC、密码哈希等关键路径
+  - `cache_layer`: CompositeCache 各操作性能
+  - `import_conflict`: CSV 导入冲突检测策略对比
+  - `ipc_protocol`: IPC 协议序列化/反序列化性能
+  - `password`: Argon2 密码哈希性能
+  - `utils`: 短码生成、URL 验证等工具函数性能
+- **单元测试覆盖** - 新增测试覆盖 22 个模块（JWT、缓存层、存储层、服务层、错误处理等）
+- **集成测试套件** - 新增 `link_service_tests.rs`（865 行）和 `storage_tests.rs`（695 行）
+
+### Changed
+- **Cookie 安全标志默认开启** - `cookie_secure` 默认改为 `true`，强制 HTTPS 传输 Cookie
+  - `cookie_secure=false` 时启动输出警告日志
+- **移除可配置 Cookie 名称** - 移除 `access_cookie_name` 和 `refresh_cookie_name` 配置项
+  - 改为硬编码常量，减少攻击面
+- **升级依赖** - Rust 1.93-slim，移除 OpenSSL 依赖（使用 rustls）
+
+### Improved
+- **CSV 导入冲突检测性能优化** - 全量加载 -> Bloom Filter 预筛选 -> 批量查询
+  - 预扫描 CSV 提取所有 codes，使用 Bloom Filter 快速排除肯定不存在的 codes
+  - 仅对可能存在的 codes 执行批量数据库查询
+- **CSV 导出流式化** - 使用 `stream::unfold` 实现分页流式查询（每批 1000 条）
+- **Dockerfile 构建优化** - 减少镜像层大小，静态链接编译，移除未使用的依赖
+- **查询条件构建** - 使用 SeaORM `contains()` 方法替代手动字符串拼接，防止通配符注入
+- **基准测试性能** - 手动创建运行时，避免每次迭代创建/销毁
+
+### Fixed
+- **健康检查未授权响应** - 统一业务码为 1（之前为 401），保持 API 响应格式一致性
+- **Symlink 攻击防护** - 使用 `create_new()` 原子创建 `admin_token.txt`，防止 TOCTOU 竞态条件
+- **SeaORM contains() 误用** - 移除手动添加 `%` 通配符，`contains()` 方法已自动处理
+
+### Security
+- **IPC 权限控制** - Unix socket 文件创建后设置权限为 `0600`（仅属主可读写）
+- **Admin Token 文件安全** - 原子创建文件 + Unix 权限 0600，防止 symlink 攻击
+- **登录限流增强** - 默认使用连接 IP（不可伪造），防止客户端伪造 IP 绕过限流
+- **CSRF Cookie SameSite 设置** - CSRF Cookie 使用 `Lax` 模式，防止跨站 POST 请求
+- **认证方式显式标记** - 在 `req.extensions()` 中插入 `AuthMethod`，CSRF 中间件根据标记判断是否跳过验证
+
+### Dependencies
+- 升级 Rust 至 1.93-slim
+- 移除 OpenSSL 依赖（使用 rustls）
+
+### Docs
+- 更新 Admin API 鉴权文档，新增 CSRF 防护说明
+- 更新配置文档，新增 `api.trusted_proxies` 说明
+
+### Migration Notes
+
+**⚠️ 从 v0.4.0 升级注意事项：**
+
+1. **CSRF 防护默认启用** - Web 管理面板的所有变更操作需携带 `X-CSRF-Token` header
+2. **Cookie 名称硬编码** - `access_cookie_name` 和 `refresh_cookie_name` 配置项已移除，现在固定为 `shortlinker_access` 和 `shortlinker_refresh`
+3. **Cookie Secure 默认开启** - 如需在非 HTTPS 环境使用，需显式设置 `cookie_secure=false`（启动时会有警告）
+4. **可信代理配置** - 如果在代理/负载均衡器后部署，建议配置 `api.trusted_proxies` 列表以正确识别客户端 IP
+
 ## [v0.4.0] - 2026-01-23
 
 ### 🎉 Release Highlights
@@ -908,7 +987,8 @@ v0.3.0 是一个重大版本更新，包含大量安全增强、性能优化和
 - Update README.md
 - Initial commit
 
-[Unreleased]: https://github.com/AptS-1547/shortlinker/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/AptS-1547/shortlinker/compare/v0.4.1...HEAD
+[v0.4.1]: https://github.com/AptS-1547/shortlinker/compare/v0.4.0...v0.4.1
 [v0.4.0]: https://github.com/AptS-1547/shortlinker/compare/v0.3.0...v0.4.0
 [v0.3.0]: https://github.com/AptS-1547/shortlinker/compare/v0.2.2...v0.3.0
 [v0.3.0-beta.3]: https://github.com/AptS-1547/shortlinker/compare/v0.3.0-beta.2...v0.3.0-beta.3