waka-readme-stats Docker镜像文档

镜像概述

本Docker镜像专为配合GitHub Action anmol098/waka-readme-stats 设计，提供开发指标可视化能力。通过集成WakaTime等开发统计服务数据，镜像可生成编码时间分布、语言使用占比、编辑器偏好等核心指标卡片，并自动更新至GitHub Readme文件，帮助开发者在个人或项目主页直观展示开发活动数据。

核心功能与特性

• Action无缝集成：与anmol098/waka-readme-stats Action深度适配，实现数据采集、卡片生成、Readme更新全流程自动化。
• 多维度指标展示：支持展示编码时长（今日/本周/本月/全年）、语言使用占比、编辑器/IDE使用统计、项目贡献分布等关键开发数据。
• 高度自定义配置：通过环境变量或配置文件调整卡片样式（主题颜色、尺寸）、数据时间范围、指标展示项，满足个性化需求。
• 轻量级设计：基于Alpine Linux构建，镜像体积小于50MB，运行时内存占用低于100MB，适合CI/CD环境持续运行。
• 定时自动更新：配合GitHub Action定时任务，可实现每日/每周自动更新指标卡片，无需手动维护。

使用场景与适用范围

• 个人开发者：在GitHub个人资料Readme（如username/username仓库的README.md）中展示个人开发轨迹，增强技术形象。
• 开源项目：在项目Readme中嵌入开发指标，向社区展示项目活跃度、维护频率及核心贡献者工作状态。
• 技术团队：作为团队开发规范落地工具，通过公开指标促进开发过程透明化。

使用方法与配置说明

前置条件

1. 注册WakaTime账号并配置IDE插件，获取WakaTime API密钥（在WakaTime设置页查看）。
2. 创建GitHub Personal Access Token（PAT），权限需包含repo（用于修改Readme文件），创建路径：GitHub → Settings → Developer settings → Personal access tokens。
3. 待更新的Readme文件需包含标记注释（如<!--START_SECTION:waka-->...<!--END_SECTION:waka-->），用于指定指标卡片插入位置。

环境变量配置

运行镜像需通过环境变量传入核心配置，常用参数如下：

Docker Run命令示例

直接通过Docker CLI运行（适合本地测试）：

docker run --rm \
  -e GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -e WAKATIME_API_KEY="waka_xxxxxxxxxxxxxxxxxxxxxx" \
  -e USERNAME="john-doe" \
  -e TIME_RANGE="monthly" \
  -e THEME="radical" \
  anmol098/waka-readme-stats:latest

GitHub Action工作流配置（推荐）

在目标仓库（如个人资料仓库）中创建.github/workflows/update-waka-stats.yml文件，配置自动更新流程：

name: Update WakaTime Stats

on:
  schedule:
    - cron: '0 0 * * *'  # 每日UTC 0点执行（北京时间8点）
  workflow_dispatch:  # 支持手动触发

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run waka-readme-stats
        uses: docker://anmol098/waka-readme-stats:latest
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
          WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
          USERNAME: ${{ github.repository_owner }}
          TIME_RANGE: 'weekly'
          THEME: 'dark'
          LANG_COUNT: '8'

注意：需在仓库Secrets中添加GH_TOKEN和WAKATIME_API_KEY，路径：仓库 → Settings → Secrets and variables → Actions → New repository secret。

自定义卡片样式

如需高级自定义（如隐藏特定指标、调整字体大小），可创建config.json配置文件并挂载至容器/app/config目录：

{
  "title_color": "#3498db",
  "text_color": "#666666",
  "hide": ["minutes", "hostname"],
  "line_height": 1.5
}

运行时挂载配置文件：

docker run --rm \
  -e GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -e WAKATIME_API_KEY="waka_xxxxxxxxxxxxxxxxxxxxxx" \
  -v $(pwd)/config.json:/app/config/config.json \
  anmol098/waka-readme-stats:latest

常见问题排查

• 指标卡片未更新：检查GitHub PAT权限是否包含repo，Readme文件是否包含正确的标记注释，或查看Action运行日志（GitHub → Actions → 对应 workflow → 具体任务 → Logs）。
• 数据与WakaTime不一致：WakaTime数据存在5-10分钟延迟，可等待数据同步后重试；或检查TIME_RANGE配置是否与WakaTime查看范围一致。
• 卡片样式异常：确认THEME值是否在支持列表中，或通过自定义CSS覆盖样式。