ljwx-tiny - API Key Management & Audit System

最小但真实可用的 API Key 管理和调用审计系统，用于验证 ljwx-template 完整链路。

---

📋 项目概述

ljwx-tiny 是一个企业级 API Key 管理系统，包含以下核心功能：

• ✅ API Key 管理：创建、查询、启用/禁用、软删除
• ✅ 调用审计：自动记录所有 API 调用（时间、状态、延迟、IP、Trace ID）
• ✅ 受保护接口：/api/ping 需要有效 API Key 才能访问
• ✅ 前端界面：Vue3 + Element Plus 管理界面

---

🛠️ 技术栈

• 后端：Spring Boot 3.2.1 + Java 17 + PostgreSQL 16 + Redis 7
• 前端：Vue 3.4 + TypeScript + Vite 5 + Element Plus 2.5
• 部署：Kubernetes (k3s) + Helm 3 + Argo CD + Nginx Ingress
• 可观测性：Prometheus + Grafana + Loki + Tempo

---

🚀 快速开始

本地开发

# 1. 克隆仓库并配置环境
git clone <your-repo-url>
cd ljwx-tiny
cp .env.example .env
# 编辑 .env，配置本地 Postgres 和 Redis

# 2. 启动前后端
./start_tiny.sh

访问：http://localhost:5173（前端）| http://localhost:8080（后端）

Docker Compose 验证

docker-compose up -d
docker-compose ps
# 测试 API
curl -X POST http://localhost:8080/api/api-keys -H "Content-Type: application/json" -d '{"name":"test-key"}'

部署到 Kubernetes

# 1. 创建 namespace 和 Secret（执行一次）
./scripts/setup-namespace.sh

# 2. 提交 GitOps 配置到 ljwx-deploy 仓库
# 参考：gitops/application.yaml

# 3. 验证部署
argocd app get tiny
kubectl get pods -n tiny

访问：https://tiny.omniverseai.net

一键本地部署

对于本地开发和测试，可以使用一键部署脚本：

# 从源码构建、推送镜像到 Harbor、部署到本地 k8s
./build-push-deploy.sh

该脚本会自动执行以下步骤：

• 构建后端（Spring Boot）和前端（Vue3）应用
• 构建 Docker 镜像并推送到 Harbor 仓库
• 更新 Helm values 中的镜像标签
• 部署到本地 Kubernetes 集群
• 验证部署状态

---

🎯 OpenSpec 工作流（新增）

v2.0 整合：本项目已集成 OpenSpec + 无交互执行体系，实现工程化 AI 辅助开发。

核心特点

• ✅ 5 阶段工作流：需求录入 → 任务拆解 → 开发实施 → 测试验证 → 归档交付
• ✅ 4 个检查点：只在关键节点询问，减少 96% 的重复确认（100+ 次 → 4 次）
• ✅ 权限自动化：开发阶段全自动，0 次打断
• ✅ 全程可追溯：每个阶段都有文档记录

OpenSpec 目录结构

ljwx-tiny/
├── openspec/
│   ├── AGENTS.md                     # AI 工具统一配置（PROMPT_BLUEPRINT v1.4 + OpenSpec）
│   ├── specs/                        # 已归档的规范（真理源）
│   │   ├── requirements/
│   │   ├── architecture/
│   │   ├── features/
│   │   ├── testing/
│   │   └── api/
│   ├── changes/                      # 进行中的变更（工作区）
│   │   └── 20251228-user-registration/  # 示例：用户注册功能
│   │       ├── proposal.md           # 📋 需求 + 设计（ljwx v2.0）
│   │       ├── tasks.md              # ✅ 任务清单（P0/P1/P2 分级）
│   │       ├── implementation.md     # 🔧 实现记录
│   │       └── testing.md            # 🧪 测试报告
│   ├── templates/                    # 文档模板
│   └── scripts/                      # 自动化脚本
└── .claude/
    └── settings.local.json           # 权限自动化配置

工作流程示例

1. 需求录入 ✋ 检查点 1
   AI 生成: proposal.md
   你审查: 需求 + 设计是否合理？
   批准: 回复 y

2. 任务拆解 ✋ 检查点 2
   AI 生成: tasks.md（P0/P1/P2）
   你审查: 任务是否完整？
   批准: 回复 y

3. 开发实施 🚀 全自动，0 次打断
   AI 自动执行所有 P0 任务
   实时更新 implementation.md

4. 测试验证 ✋ 检查点 3
   AI 生成: testing.md + DoD 验证
   你审查: 测试是否通过？
   批准: 回复 y

5. 归档交付 ✋ 检查点 4
   AI 输出: 交付报告 + GitOps 变更建议
   你确认: 是否归档？

如何使用

开发新功能时，直接告诉 AI：

实现用户注册功能

AI 会自动：

1. 创建 openspec/changes/YYYYMMDD-user-registration/
2. 生成 proposal.md（符合 ljwx 标准）
3. 等待你审查（检查点 1）
4. 生成 tasks.md（P0/P1/P2 分级）
5. 等待你审查（检查点 2）
6. 自动执行所有 P0 任务（0 次打断）
7. 生成测试报告，等待审查（检查点 3）
8. 归档并提供 GitOps 变更建议（检查点 4）

详细文档

• 工作流规范：openspec/AGENTS.md - 完整的 OpenSpec + ljwx 规范
• 示例 Change：openspec/changes/20251228-user-registration/
• 权限配置：.claude/settings.local.json

GitHub Projects 集成（新增 v2.0）

本项目已集成 GitHub Projects + Spec 驱动开发，实现项目进度可视化管理。

核心特点：

• 📊 状态机管理：Draft → Spec Ready → In Dev → In Test → Done
• 📝 Spec 强绑定：没有 Spec 不开发，Spec 未评审不合并
• 🤖 AI 受控执行：AI 只根据 Spec 执行，不自行决定功能范围
• ✅ 三段验证：docker-compose + helm + K8s 全部通过

快速开始：

1. 查看 GitHub Projects 指南
2. 使用 Spec 模板 创建功能 Spec
3. 在 GitHub 创建 Issue（使用 .github/ISSUE_TEMPLATE/feature.md）
4. AI 根据 Spec 自动执行开发
5. 跟踪 GitHub Projects Board 进度

完整示例：

• Spec 示例：specs/user-registration.md
• 7 天落地计划：docs/7-DAY-PLAN.md
• Issue 模板：.github/ISSUE_TEMPLATE/feature.md
• PR 模板：.github/PULL_REQUEST_TEMPLATE/feature.md

---

📚 文档

• 验证指南：VERIFICATION.md - 完整的三段验证步骤
• OpenAPI 规范：backend/openapi/api-key-management.yaml
• 开发守则：PROMPT_BLUEPRINT.md - ljwx v1.4 工程规范
• OpenSpec 工作流：openspec/AGENTS.md - v2.0 整合版

---

📦 交付物清单

代码

• ✅ OpenAPI 规范（5个接口）
• ✅ Flyway 迁移脚本（V1__init.sql）
• ✅ Spring Boot 后端（完整实现 + 测试）
• ✅ Vue3 前端（列表、创建、审计页面）

部署

• ✅ Helm Chart（支持 backend + frontend 双服务）
• ✅ GitOps Application YAML（Argo CD）
• ✅ CI/CD 配置（GitHub Actions）
• ✅ docker-compose.yaml（本地验证）

可观测性

• ✅ Grafana Dashboard JSON
• ✅ Prometheus 指标暴露
• ✅ Loki 日志集成
• ✅ Tempo 链路追踪

---

🔥 功能验证

1. 创建 API Key

curl -X POST https://tiny.omniverseai.net/api/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app-key"}'

2. 调用受保护接口

curl -X POST https://tiny.omniverseai.net/api/ping \
  -H "X-API-Key: ljwx_abc123..."

3. 查询审计日志

curl https://tiny.omniverseai.net/api/audit-logs

---

📊 可观测性

• Grafana Dashboard：observability/grafana-dashboard.json
• Metrics: https://tiny.omniverseai.net/api/actuator/prometheus
• Logs: {namespace="tiny", app="tiny-backend"}（Loki）
• Traces: 通过 trace_id 在 Grafana Tempo 查询

---

🏗️ 架构设计

API Key 校验流程

Client → Ingress (TLS) → Backend → ApiKeyInterceptor
                                        ├─ validateApiKey()
                                        ├─ updateLastUsed()
                                        └─ logApiCall()
                                              ↓
                                        Controller → Response

数据库表结构

• t_api_key: API Key 存储（SHA256 哈希）
• t_api_call_log: 调用审计记录

完整 DDL：backend/src/main/resources/db/migration/V1__init.sql

---

🔒 安全考虑

• ✅ API Key SHA256 哈希存储
• ✅ HTTPS 强制（cert-manager 自动签发）
• ✅ 最小权限原则（独立 database + user）
• ✅ Secret 隔离（namespace 级别）
• ✅ 完整审计日志（可追溯）

---

📞 支持

• 项目：ljwx-tiny v1.0.0
• 组织：LingJingWanXiang
• 生成时间：2025-12-27

---

🎉 所有关键链路验证通过！

这个项目可作为你们所有后续项目的参考模板。