wangjia/pangolin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity
52 Commits 7 Branches 47 Tags
605bfa1ec9239a1cb5dfd5eae465b363e22d4c8d
Commit Graph

52 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
wangjia 605bfa1ec9 feat(nodes): gRPC server + Hub + Redis pub/sub cross-instance delivery (tsk__58l3wTLvaSn) 
Implements AgentService gRPC server with all 6 RPCs (Enroll/Register/Heartbeat/
Subscribe/Ack/ReportUsage), Hub command routing with Redis ZSET at-least-once
persistence and cross-instance pub/sub delivery, LoadCache for node:load metrics,
NodeStore SQL interface + MySQL implementation, and full mTLS gRPC listener in main.

Integration tests: 18 tests covering full Enroll→Register→Heartbeat→Subscribe→Ack
flow, reconnect resume with last_command_id, and cross-instance pub/sub delivery
via bufconn + miniredis + mockNodeStore + real mTLS certificates.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 17:30:42 +08:00
wangjia 9423069a0b merge: maestro/tsk_iP5-_Ztq5THx [tsk_iP5-_Ztq5THx] 2026-06-13 17:04:18 +08:00
wangjia b456a8816f merge: maestro/tsk_V9IrIk2g5Q78 [tsk_V9IrIk2g5Q78] 2026-06-13 17:04:17 +08:00
wangjia 3bcf1d7b4c merge: maestro/tsk_NU9JuUweHWMt [tsk_NU9JuUweHWMt] 2026-06-13 17:04:17 +08:00
wangjia 96040c802f merge: maestro/tsk_3FIPC8lSnAfJ [tsk_3FIPC8lSnAfJ] 2026-06-13 17:04:17 +08:00
wangjia c642daec42 merge: maestro/tsk_acMYQ-Z-EIF_ [tsk_acMYQ-Z-EIF_] 2026-06-13 17:04:17 +08:00
wangjia 5a6b4a2dbb merge: maestro/tsk__R8M4jEw43JR [tsk__R8M4jEw43JR] 2026-06-13 17:04:17 +08:00
wangjia 5a485fbcf6 merge: maestro/tsk_FrRarw9YO8Nf [tsk_FrRarw9YO8Nf] 2026-06-13 17:04:17 +08:00
wangjia 908f75de75 merge: maestro/tsk_VRzw-af__qWx [tsk_VRzw-af__qWx] 2026-06-13 17:04:17 +08:00
wangjia b7aca4848a merge: maestro/tsk_rcNKc3GQHBUd [tsk_rcNKc3GQHBUd] 2026-06-13 17:04:17 +08:00
wangjia 6f3ceba7a9 merge: maestro/tsk_eu2qVvni1HJR [tsk_eu2qVvni1HJR] 2026-06-13 17:04:17 +08:00
wangjia e2646346a6 feat(web/usercenter): Next.js 用户中心静态导出 + mock/http 双数据层 (tsk_3FIPC8lSnAfJ) 
新建 web/usercenter/：Next.js App Router + output:'export' 纯静态导出，
直接复用 design/ui_kits/usercenter React 源码（概览/订阅/兑换/邀请/设置）。

阶段 A（mock，本提交）：
- 复刻五大页面，明/暗 × zh/en 四态；colors_and_type.css 原样链入；
  顶栏主题切换 + 语言段控，移动端底部 Tab + 左右滑动切换。
- 设置页新增：偏好(语言/主题) + 设备管理(列表/移除/二次确认+刷新) +
  TOTP 2FA(绑定二维码占位+密钥/验证/解禁)，登录二段式 TOTP。
- 数据层 lib/api：ApiClient 抽象 + MockClient/HttpClient 双实现，构建期
  NEXT_PUBLIC_API_MODE 切换；统一错误体 {code,message_zh,message_en} → 双语映射。
- 会话：access token 仅内存，refresh header token + localStorage，静默续期，
  登出失效（取舍：静态导出无服务端 cookie 能力，详见 README）。
- 安全：构建期注入 SRI(sha384)；_headers 严格 CSP + 安全基线；
  红线词扫描(铁律13) CI 红线，零命中。

阶段 B（占位待联调）：HttpClient 已写好域名池+退避重试+401 续期；
TOTP/登录二段式端点占位待 #1 契约增补；me/redeem/devices 切真实链路依赖 #2/#3/#4。

验证：npm run lint / redline / build 均通过，静态产物 out/ 无服务端依赖。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 15:23:18 +08:00
wangjia 6ec7cd8146 merge: maestro/tsk_V9IrIk2g5Q78 [proto 契约 + buf 工具链] (tsk_FrRarw9YO8Nf) 
合并 proto 契约 + buf 工具链任务到 main（已含 apierr + idgen + CONVENTIONS.md）：

- server/proto/pangolin/agent/v1/agent.proto: AgentService 6 个 RPC（Enroll/Register/
  Heartbeat/Subscribe/Ack/ReportUsage）及全量消息类型，隐私红线注释保留
- server/buf.yaml: v2 格式，STANDARD lint + FILE breaking 规则
- server/buf.gen.yaml: remote protoc-gen-go v1.36.4 + protoc-gen-go-grpc v1.5.1 插件
- server/internal/pb/: 生成的 agent.pb.go + agent_grpc.pb.go 提交入库
- server/Makefile: 新增 proto / proto-lint / proto-breaking 目标
- server/tools.go: 新增 buf v1.70.0、protoc-gen-go、protoc-gen-go-grpc 工具依赖
- server/go.mod / go.sum: 合并 buf 工具链依赖；github.com/google/uuid 保留为 direct
  依赖（idgen 直接 import）；go 版本升至 1.25.10

冲突解决：两侧均修改 go.mod，以 proto 分支（超集）为基础，将 google/uuid 移至
直接依赖 require 块，保留 apierr/idgen 的已有文件不变。

go build ./... ✓  |  go test ./internal/apierr/... ./internal/idgen/... ✓

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 15:11:11 +08:00
wangjia d88c1ae647 merge: maestro/tsk_x7wrlA87orsY [devices + 订阅校验中间件] (tsk_VRzw-af__qWx) 
手动合并 tsk_x7wrlA87orsY（设备管理 + 订阅校验中间件）到 main：

冲突解决：
- server/internal/apierr/apierr.go：保留 tsk_GXDoc3Cs07Rn 版本（New/StatusFor/
  Middleware/ErrConflict/改善文档），并入 tsk_x7wrlA87orsY 新增的 ErrAccountBanned
  及对应 StatusFor case（→ 403）。

新增文件（来自 tsk_x7wrlA87orsY）：
- server/internal/devices/doc.go       package 文档（替换占位 stub）
- server/internal/devices/context.go   CtxKeyUserID / Plan / WithPlan / PlanFromCtx
- server/internal/devices/handler.go   GET /v1/me/devices · DELETE /v1/me/devices/{id}
- server/internal/devices/middleware.go SubscriptionMiddleware · CheckDeviceQuota · RequirePaidTier
- server/internal/devices/service.go   RegisterIfAbsent / DeleteDevice / ResolvePlan + 纯函数 resolveEffectivePlan
- server/internal/devices/store.go     MySQL 数据访问层
- server/internal/devices/service_test.go          15 个单测（全通过）
- server/internal/devices/devices_integration_test.go  testcontainers 集成测试

OpenAPI 更新（来自 tsk_x7wrlA87orsY）：
- server/api/openapi.yaml：SubscriptionInfo.source 枚举补 free
- design/server/openapi.yaml：SubscriptionInfo.source 枚举补 admin, free

测试：go build ./... ✓；go test ./internal/apierr/... ✓（8 tests）；
      go test ./internal/devices/... ✓（15 tests）。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 15:09:51 +08:00
wangjia c84b6ea7da merge: maestro/tsk_iP5-_Ztq5THx [桥接 API 面 Channel 契约 + 三端原生骨架] [tsk_rcNKc3GQHBUd] 
合并冲突补救：原分支从 merge base 7871512 分叉，仅修改 client/ 目录，
与 main 新增的 server/(apierr/idgen/CONVENTIONS.md) 完全不重叠，
无真实文件冲突，手动应用 feature branch 的全部 client/ 改动。

client 侧新增：
- lib/bridge/vpn_bridge.dart      — Dart↔原生通道契约（冻结）
- lib/bridge/vpn_bridge_mock.dart — 假内核，UI 联调用
- lib/bridge/kernel_process.dart  — 桌面子进程管理接口
- ios/PacketTunnel/{Info.plist,PacketTunnelProvider.swift} — NEPacketTunnel 骨架
- ios/Runner/VpnManager.swift     — NETunnelProviderManager 封装
- android/.../PangolinVpnService.kt — VpnService 骨架
- android/.../VpnEventBus.kt      — Application 级状态总线
- test/bridge/vpn_bridge_mock_test.dart — 桥接层单元测试

client 侧修改：
- android/.../MainActivity.kt    — 注册三通道（MethodChannel + 2×EventChannel）
- android/.../AndroidManifest.xml — 声明 FOREGROUND_SERVICE + PangolinVpnService
- ios/Runner/AppDelegate.swift   — 注册通道 + VpnManager 初始化
- ios/Runner/Info.plist          — 新增 NSVPNUsageDescription
- ios/Runner.xcodeproj/project.pbxproj — 添加 PacketTunnel extension target
- lib/widgets/connect_button.dart — VpnStatus 迁移到 bridge/vpn_bridge.dart
- lib/widgets/home_shell.dart    — error 状态 UI 分支补全
 2026-06-13 14:58:38 +08:00
wangjia 30e73b31c2 merge: maestro/tsk_GXDoc3Cs07Rn [apierr + idgen + CONVENTIONS.md] 2026-06-13 14:42:47 +08:00
wangjia f76e1797c2 merge: maestro/tsk_rBPr0Xuy10bz [tsk_rBPr0Xuy10bz] 探针汇聚入口 + Redis 探针存储 (tsk_eu2qVvni1HJR) 
Manually apply changes from maestro/tsk_rBPr0Xuy10bz that could not be
auto-merged due to uncommitted changes on main at merge time.

Added:
- server/internal/scheduler/probe/types.go  – frozen schema types (ReportRequest,
  VantagePoint, NodeReport, L1/L2/L3Result, ProbeSnapshot)
- server/internal/scheduler/probe/store.go  – Redis Store: SaveReports, CheckAndMarkSeen,
  SnapshotsByNode, AliveProbes with TTL constants and key-schema docs
- server/internal/scheduler/probe/ingest.go – IngestHandler (POST /probe/report),
  HMAC-SHA256 auth + timestamp window + replay prevention via SetNX
- server/internal/scheduler/probe/ingest_test.go – 17 tests (auth failures, integration,
  Store unit tests); all pass with miniredis

Updated:
- server/cmd/server/main.go – register /probe/report route when PROBE_SECRETS env is set

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 14:35:24 +08:00
wangjia 4df8dc6f87 feat(web): 官网 ui_kits/website → Astro 纯静态 SSG 迁移 (tsk_acMYQ-Z-EIF_) 
新建 web/website/（Astro 零 SSR）：

- 组件迁移：交互块保留 .jsx 经 @astrojs/react（Header/AnnouncementBar/SignupForm/PricingPlans），纯展示块转 .astro 去运行时 JS；像素以原型为基准。
- 令牌同源：build-tokens.mjs 从 design/colors_and_type.css 生成 tokens.gen.css，仅剔除第三方 Google Fonts @import，数值不改。
- 字体自托管：@fontsource（Sora/Manrope/Noto Sans SC/JetBrains Mono），无第三方 CDN。
- 图标：Lucide 构建期内联 SVG（替代 unpkg CDN），零运行时、零 CDN。
- i18n：/（zh）与 /en/（en）双路由单显，语言切换组件；文案沿用 ui_kits 脱敏文案。
- 安全：public/_headers 严格 CSP（全 self + 自托管资源 + 内联片段 sha256，无 unsafe-inline）+ HSTS；无支付表单。
- CI：.gitea/workflows/website.yml 构建（红线扫描+lint+CSP 哈希）→ 同时发布 Cloudflare Pages 主站与镜像。
- 灾备：README 写明干净环境 npm ci && npm run build 可直接部署到任意静态托管；dist 指纹确定性，主站镜像一致。

测试：npm run lint（0 error）/ npm test（build+CSP 哈希注入+红线扫描 0 命中）/ 两次干净构建 dist 指纹一致。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 14:26:40 +08:00
wangjia 7d89ec9d91 feat(infra/domains): 域名池 + CDN 前置 + 签名端点分发 (tsk_NU9JuUweHWMt) 
- domains.md: 四组域名隔离登记 + 冷备池 ≥5 + 启用流程（不含身份信息）
- cdn/terraform: Cloudflare 配置即代码（WAF/bot/速率限制/代理DNS/回源鉴权注入）+ 30min 重放 Runbook
- server/internal/originauth: 回源鉴权中间件，非 CDN 网段或鉴权头不符一律 403，支持双值轮换
- tools/endpoint-signer: 离线 Ed25519 签名 CLI（端点 + 公告文档，单调版本防回滚，key_id 双公钥轮换）
- tools/publish-mirrors: ≥3 镜像发布 + hash 一致性校验 + 故障转移取回
- CLIENT-CONTRACT.md: schema/验签/防回滚/合并/兜底链/channel 客户端契约
- 出站独立出口要求写入部署文档；私钥/token/身份信息一律不入库

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 14:21:55 +08:00
wangjia f03d2dc8a6 feat(agent): node agent — enroll/mTLS, heartbeat, command stream, sing-box 用户表 (tsk__R8M4jEw43JR) 
与控制面同仓同 go.mod，新增节点 agent 实现：

- proto/agent/v1/agent.proto + internal/pb/agentv1：冻结的控制面↔agent gRPC 契约
  （Enroll/Register/Heartbeat/Subscribe/Ack/ReportUsage）。仓库尚无 protoc 流水线，
  暂以手写 Go 类型 + JSON gRPC codec 实现，与 proto 1:1 对应，待 protoc 接入即可替换。
- internal/agentd：
  - enroll.go：首启生成 EC 密钥+CSR，持 bootstrap token 调 Enroll 换 90d 节点证书
    （CN=node_uuid），落 /etc/pangolin-agent/，此后 mTLS。
  - conn.go(agent.go)+creds.go：mTLS 主动拨号 + 指数退避重连；重连携带 last_command_id；
    Register 取 ConfigSnapshot 全量配置覆盖本地。
  - heartbeat.go：30s 上报 peer/带宽/CPU + config_version；need_full_resync→全量同步。
  - command.go：消费 Subscribe，Upsert/Revoke/Rotate/ApplyConfig/Lifecycle 幂等处理后
    Ack（at-least-once，按 command_id 去重）。
  - singbox.go+render.go：内存用户表 + 落盘 state.json（仅 dp_uuid+expires_at）；任何变更
    渲染完整 sing-box 配置（REALITY users[uuid,flow] + Hy2 users[派生口令]）→ 500ms 去抖
    合并 → systemd 重启。
  - ttl.go：凭证 TTL 定时移除并上报。
  - usage.go：按 dp_uuid 聚合上报，绝无 user_id/email/目的地址。
  - derive.go：Hy2 口令 = HMAC-SHA256(key, dp_uuid)，与控制面同源派生。
- cmd/agent：入口（flag/env 配置）。
- infra/cloud-init/{node.yaml.tmpl,install-node.sh,README.md}：一段式安装，下载锁定版本
  二进制并校验 SHA-256，systemd 拉管，首启即 Enroll/Register。shellcheck -S warning 通过。

测试（bufconn mock 控制面，无需 docker）：Enroll→Register→Heartbeat 全流转；Upsert/Revoke
渲染正确；Rotate 宽限期新旧并存到点移除；TTL 自动移除并上报；断流重连 last_command_id
续发不丢不重；need_full_resync 触发重注册；state.json 恢复；去抖合并；扫描确认无身份字段。
go test -race ./internal/agentd/... ./internal/pb/... 通过；go vet ./... 通过。

落实 doc/04 §2 节点无状态化与 doc/06 §3 数据面红线（节点仅见 dp_uuid）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 12:26:58 +08:00
wangjia 6e2657049e feat(proto): add agent.proto contract + buf toolchain (tsk_V9IrIk2g5Q78) 
Introduces the frozen control-plane ↔ agent gRPC contract and the full
buf v2 code-generation pipeline that task #6/#14/#15 depend on.

Changes:
- server/proto/pangolin/agent/v1/agent.proto: AgentService with 6 RPCs
  (Enroll, Register, Heartbeat, Subscribe, Ack, ReportUsage) and all
  supporting message types (Command + 5 payload variants, ConfigSnapshot,
  CredentialEntry, NodeLoad, UsageItem).  Red-line comments prohibit
  user_id/email and destination-address fields per privacy policy.
- server/buf.yaml: v2 format, STANDARD lint + FILE breaking rules.
- server/buf.gen.yaml: remote protoc-gen-go v1.36.4 + protoc-gen-go-grpc
  v1.5.1 plugins, out=internal/pb, paths=source_relative.
- server/internal/pb/pangolin/agent/v1/: generated agent.pb.go +
  agent_grpc.pb.go committed to repo (CI diff-clean verified).
- server/Makefile: proto / proto-lint / proto-breaking targets added.
- server/tools.go: buf v1.70.0, protoc-gen-go, protoc-gen-go-grpc pinned.
- server/go.mod / go.sum: buf and grpc tool deps added via go mod tidy.

Acceptance verified:
  buf lint  → zero warnings
  buf generate × 2 → git diff clean (idempotent)
  go build ./... → passes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 12:13:43 +08:00
wangjia 4992d916d0 feat(bridge): 桥接 API 面 Channel 契约 + 三端原生骨架 [tsk_iP5-_Ztq5THx] 
MethodChannel pangolin/vpn (start/stop/getStatus/selectOutbound/
getActiveOutbound/setKillSwitch) + 双 EventChannel (status/stats)
契约定义在 lib/bridge/vpn_bridge.dart 头部注释冻结。

- Dart: VpnBridge 抽象接口 + VpnNativeBridge 原生实现 + VpnBridgeMock
  假内核（含 connectDelay/statsInterval 可配参数）
- Dart 桌面: kernel_process.dart KernelProcess/ClashApiClient 接口骨架
- Android: PangolinVpnService (VpnService 骨架 + 前台通知占位) +
  VpnEventBus 解耦总线 + MainActivity MethodChannel/EventChannel 注册
- iOS: PacketTunnelProvider (NEPacketTunnelProvider 骨架) + VpnManager
  (NETunnelProviderManager + NEVPNStatus 订阅) + AppDelegate 通道注册
  + Xcode project.pbxproj 添加 PacketTunnel extension target
- Widget: VpnStatus enum 迁移至 bridge/vpn_bridge.dart (+error 态)，
  connect_button/home_shell 更新穷举匹配
- Test: test/bridge/vpn_bridge_mock_test.dart 覆盖 start→connecting→on
  →stop→off 序列、stats 周期推帧、selectOutbound 重连序列、schema 回测

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 12:06:03 +08:00
wangjia b64c002a33 feat(tsk_GXDoc3Cs07Rn): apierr + idgen + CONVENTIONS.md 
apierr:
- Add New() constructor, StatusFor() HTTP-status mapping
- Add ErrUnauthorized, ErrForbidden, ErrNotFound, ErrConflict predefined errors
- Add chi-compatible Middleware for panic(*Error) → JSON recovery
- Add apierr_test.go (8 tests; covers New, StatusFor, WriteJSON, Middleware)

idgen:
- Implement idgen.go: New()/NewString() (UUID v7 via google/uuid v1.6.0)
- Implement GenerateCode/CanonicalizeCode/HashCode (Crockford Base32 moved from codes)
- Add idgen_test.go (12 tests; UUID v7 ordering/uniqueness + Crockford format/normalization/check)

codes:
- Refactor generator.go to delegate GenerateCode/Canonicalize/Hash to idgen
- All existing codes generator tests continue to pass unchanged

server:
- Add CONVENTIONS.md covering package structure, error handling, ID generation,
  database conventions, handler templates, auth context, testing, and logging rules
- Move google/uuid from indirect to direct dependency in go.mod

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 11:58:38 +08:00
wangjia 787151245e merge: maestro/tsk_tFMU7-hKzfOf [tsk_tFMU7-hKzfOf] codes 激活码模块 
解决与 1A 骨架的冲突：module 统一为 github.com/wangjia/pangolin/server
（codes 分支原用 pangolin/server，7 个源文件 import 已改写）；
go.mod require 并集(redis 取 9.20.1)；Makefile 以骨架为基底并入
build-codegen/test-unit/test-integration target。
go build/vet 通过，codes 单测通过。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 03:03:11 +08:00
wangjia a139ef937a merge: maestro/tsk_iRa5iBC4v7Tu [tsk_iRa5iBC4v7Tu] Flutter 客户端工程搭建（演示态跑通） 2026-06-13 03:01:31 +08:00
wangjia 8c516d4f2a merge: maestro/tsk_FUQws_DMIcXa [tsk_FUQws_DMIcXa] mTLS/CA + 引导 token 框架 
解决与 Go 骨架(1A)的 add/add 冲突：go.mod 统一 module 路径为
github.com/wangjia/pangolin/server，require 取并集；setup.sh 合并两边意图。
go build ./... 与 go test ./internal/mtls/... 通过。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-06-13 03:01:31 +08:00
wangjia 37b18d4293 merge: maestro/tsk_9uMrd9kUpmVA [tsk_9uMrd9kUpmVA] 数据面定稿 + 修订 ARCHITECTURE.md connect 契约 2026-06-13 02:57:25 +08:00
wangjia 2112230d57 merge: maestro/tsk_A1HkEdRbXLGY [tsk_A1HkEdRbXLGY] openapi.yaml 契约(13 操作 + 全量 schema) 2026-06-13 02:57:25 +08:00
wangjia dc7a4f12d7 merge: maestro/tsk_P5b5nIrEsfrV [tsk_P5b5nIrEsfrV] CI 流水线 2026-06-13 02:57:25 +08:00
wangjia 3f0f82eca0 merge: maestro/tsk_L2k2VrEujof8 [tsk_L2k2VrEujof8] Go 模块骨架 + 工具链(go.mod/tools.go/Makefile) 2026-06-13 02:57:25 +08:00
wangjia 18869bc1fa merge: maestro/tsk_paiqu21eZIuw [tsk_paiqu21eZIuw] MySQL migration 7 文件 + plans seed 2026-06-13 02:57:25 +08:00
wangjia adfd8ce3f2 merge: maestro/tsk_bYv-CoKSwgAC [tsk_bYv-CoKSwgAC] 备份与灾备演练 2026-06-13 02:57:25 +08:00
wangjia afcd7b325c feat(codes): implement activation-code module (tsk_tFMU7-hKzfOf) 
Implements server/internal/codes/ with all required functionality:

## Generator (generator.go)
- Crockford Base32 16-char codes (15 data + 1 Crockford mod-37 check char)
- crypto/rand for unbiased random generation with rejection sampling
- Canonicalize(): I/L→1, O→0 folding, hyphen/space stripping
- Hash(): SHA-256 of canonical plaintext (only value stored in DB)
- Algorithm hard-coded; check char detects all single-char substitution errors

## Store (store.go)
- MySQL-backed via database/sql
- CreateBatch / CreateCode with ErrDuplicate on UNIQUE conflict
- FindCodeByHashForUpdate: SELECT … FOR UPDATE for row-level concurrency control
- MarkRedeemed, ExtendSubscription, CreateSubscription, GetActiveSubscriptions
- WriteAuditLog, CodeExistsByHash
- BeginTx at READ COMMITTED (FOR UPDATE provides row exclusivity)

## Service (service.go)
- Redeem(): 9-step flow with full idempotency and concurrency safety
  - isLocked / recordFail / clearFail via Redis key redeem:fail:{user_id}
  - SELECT … FOR UPDATE → single winner under N-concurrent redemptions
  - Same-plan: extends existing subscription (max(expires_at,now)+days)
  - Cross-plan: creates new subscription (max(now,latest)+days)
  - Idempotent: same user re-submits → 200 without re-applying
  - 5 failures → ACCOUNT_LOCKED for 1 hour (sliding window via Redis)
- CreateBatch(): generates N codes, stores hashes, returns plaintext once
  - Automatic retry on hash collision (birthday probability ≈10⁻⁸)

## Webhook (webhook.go)
- POST /webhook/store/codes — outside /v1, no JWT required
- HMAC-SHA256 with hmac.Equal constant-time comparison
- ±5 min timestamp window
- Redis SetNX nonce deduplication (15-min TTL)
- Idempotent: duplicate nonce → 200; duplicate code_hash → 200

## HTTP Handler (handler.go)
- POST /v1/redeem endpoint wired to Service.Redeem
- Reads userID from context key (set by JWT middleware from auth module)
- Bilingual error responses {code, message_zh, message_en}

## Export (export.go)
- ExportCSV(): streams plaintext codes to io.Writer as CSV
- Plaintext NEVER stored in DB; only SHA-256 hash persists

## CLI (cmd/codegen/main.go)
- codegen -plan -days -count -channel -note -dsn [-out]
- Transition tool until admin panel (#8) is ready
- Outputs CSV to stdout or file; warns operator about plaintext sensitivity

## Infrastructure (skeleton)
- internal/config/config.go: env-var configuration
- internal/db/db.go: MySQL connection pool helper
- internal/redisutil/redis.go: Redis client constructor
- internal/apierr/apierr.go: bilingual error types
- migrations/001_init.sql: DDL for codes module tables
- go.mod with all dependencies

## Tests
- generator_test.go (unit, no deps):
  - Format, uniqueness (10k codes, zero collisions), normalization,
    check-char detection of all single-char errors, hash consistency
- webhook_test.go (unit, no deps):
  - Signature rejection, missing signature, stale/future timestamp,
    missing nonce, constant-time HMAC comparison
- service_test.go (//go:build integration, testcontainers):
  - N=20 concurrent redeemers → exactly 1 winner
  - Idempotent redeem returns success for same user
  - Other-user redemption → CODE_REDEEMED + failure counted
  - 5 failures → ACCOUNT_LOCKED on 6th attempt
  - Same-plan extension: expires_at precision assertion
  - Cross-plan creation: new subscription row
  - Audit log written on every successful redemption
  - CSV export: no plaintext in DB, hash present
  - Webhook nonce replay: idempotent 200
  - Webhook same-hash: idempotent 200, single DB row

Run unit tests: make test
Run integration tests: make test-integration (requires Docker)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 02:16:16 +08:00
wangjia 526e7f2f33 feat(tsk_iRa5iBC4v7Tu): Flutter 客户端工程搭建(演示态) 
基于 design/flutter/ 起步包在 client/ 下建立 Flutter 工程：

- pubspec.yaml：flutter_svg / lucide_icons / google_fonts 依赖；
  SVG 资产注册；字体由 google_fonts 运行时加载，无需本地 ttf
- lib/pangolin_theme.dart：完整设计令牌（色阶 / 间距 / 圆角 /
  动效 / 文字阶），PangolinText 改用 GoogleFonts getter，
  PangolinTheme.light / .dark 开箱即用
- lib/main.dart：runApp + 明暗主题 + 登录 → 引导 → 主框架 RootFlow
- lib/widgets/：全套组件雏形
    pangolin_icons    Lucide 图标映射
    pangolin_button   胶囊按钮四态
    country_code      国家码块 + 信号条
    status_pill       色点胶囊
    connect_button    核心连接键三态（off/connecting/on + 动画）
    server_tile       服务器列表行
    plan_card         套餐卡（专业版渐变高亮）
    auth_screen       登录 / 注册（邮箱验证码 + 设密码）
    onboarding_screen 首次引导 PageView（3 屏可滑动 + 进度点）
    home_shell        底部 4 Tab（连接/节点/统计/账户 + 状态机）
    account_screens   套餐选择 / 设备管理 / 兑换 / 联系我们
    pangolin_logo     PangolinMark / BrandLockup / AppIcon（SVG）
- assets/：logo-mark / logo-mark-white / logo-wordmark / app-icon（SVG）
- android/：Kotlin 主 Activity + Manifest + Gradle 配置
- ios/：Runner.xcodeproj + xcscheme + Podfile + AppDelegate + storyboard

运行方式（cd client/）：
  flutter pub get && flutter run

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 02:15:42 +08:00
wangjia 73fd281bb5 feat(mtls): implement mTLS/CA + bootstrap token framework [tsk_FUQws_DMIcXa] 
ECDSA P-256 self-signed CA with disk persistence (load-or-generate),
CSR signing (CN=nodeUUID, 90d validity, EKU=ClientAuth), one-time
bootstrap tokens via Redis GETDEL (15min TTL), CRL revocation with
Redis SET + DB interface, gRPC unary+stream interceptors that extract
CN from verified TLS chains (Enroll whitelisted, others require cert),
and NewServerTLSConfig (VerifyClientCertIfGiven + TLS 1.3 + CRL hook).

Frozen API: SignCSR / CAPEM / IssueToken / ConsumeToken / Revoke /
            NewServerTLSConfig / UnaryServerInterceptor / NodeUUIDFromContext

Tests cover: CA sign+verify, token one-time guarantee, TTL expiry,
             revocation rejection, interceptor whitelist (5 categories).
             Redis layer backed by miniredis in tests.

Run setup.sh from server/ to fetch deps and verify tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:44:21 +08:00
wangjia ab2bbaf683 tsk_9uMrd9kUpmVA: 数据面定稿 + 修订 ARCHITECTURE.md connect 契约 
决策：libbox 统一承载 REALITY/Hy2 outbound（方案 C），弃用 WireGuard peer 注册。
现网 deploy/ 基础设施（singbox Hy2 + xray REALITY）已验证，零改动复用。

变更文件：
- design/server/ARCHITECTURE.md v0.2：
  · §0 数据面描述改为 sing-box libbox (REALITY/Hy2)
  · §1 拓扑图更新（wireguard+agent → singbox+agent，客户端标注 libbox 内嵌）
  · §2 devices 表移除 pubkey；nodes 表改为 reality_public_key/short_id/uuid/hy2_password
  · §3 connect 响应由 WireGuard 配置改为完整 sing-box config JSON
  · §3.1（新增）connect 契约详细规范：四块 inbounds/outbounds/route/dns、
    客户端透传原则、字段与 deploy/ 模板逐字段对照、占位符替换说明
  · §4.3 连接流程更新（peer 注册 → config JSON 渲染下发）
  · 附录 A（新增）v0.1→v0.2 变更汇总
- doc/plans/11-libbox-bridge.md（新建）：
  完整决策记录（背景/备选/结论/影响面），任务链 11A→11C→11D/E/F→11H
- doc/plans/client-connect-config.example.json（新建）：
  最小示例 config，字段与 deploy/ 模板对齐，可用 sing-box check -c 校验

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:43:17 +08:00
wangjia 58c6eb721e feat: 新增 server/api/openapi.yaml — v1 API 完整契约(tsk_A1HkEdRbXLGY) 
OpenAPI 3.0.3，覆盖 doc/02 §2 全部 15 个操作：
  - 认证 4（sendVerificationCode/register/login/refreshToken，security:[]）
  - 账户 3（getMe/listDevices/deleteDevice）
  - 商业 3（redeemCode/adsUnlock/listPlans）
  - 节点 3（listNodes 含 304/connectNode/disconnectNode）
  - 用量 1（getUsage）、公告 1（listNotices）

全量 schema：Error·TokenPair·Me·UserInfo·SubscriptionInfo·TodayUsageSummary·
Device·Plan·RedeemResult·NodeDirectory·Node·ConnectCredential·
RealityParams·Hysteria2Params·UsagePoint·Notice

安全约定：bearerAuth(JWT RS256) 全局；auth 四操作 security:[]；
components/responses 统一 Error 引用；429 TooManyRequests 带 Retry-After；
节点目录不含密钥，密钥仅由 connect 端点下发；对外 ID 全部 uuid 格式。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:29:31 +08:00
wangjia 1629385c70 feat(server): Go 模块骨架 + 工具链 [tsk_L2k2VrEujof8] 
新建 server/ Go 模块：
- go.mod: module github.com/wangjia/pangolin/server, Go 1.22
  依赖: go-chi/chi/v5, google/uuid
- tools.go: //go:build tools 锁定 oapi-codegen / golang-migrate 版本
- cmd/server/main.go: chi router + GET /healthz → {"status":"ok"}，监听 :8080
- cmd/migrate/main.go: 占位入口（实逻辑归 1e）
- internal/{config,store,apierr,idgen,auth,codes,devices,nodes,usage,admin}/doc.go
  各包职责说明
- Makefile: build/test/vet/lint/generate/migrate-up/migrate-down
- .golangci.yml: govet/errcheck/staticcheck/revive/gofmt 基线
- README.md: 定位 + 目录树 + make 入口说明
- setup.sh: 首次 go mod tidy 引导脚本（go.sum 需运行后生成）

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:28:37 +08:00
wangjia b4114c93ee feat(db): add MySQL migrations 000001-000007 covering all 12 tables + seed [tsk_paiqu21eZIuw] 
- 000001: users + devices（账户 / 设备，含 argon2id pw_hash、dp_uuid）
- 000002: plans + subscriptions（套餐口径来自 design/CLAUDE.md §7）
- 000003: code_batches + codes（SHA-256 code_hash，明文不入库）
- 000004: usage_daily + audit_log（最小数据原则 + JSON meta）
- 000005: providers + nodes（providers 先建，nodes FK 引用）
- 000006: node_events（9 值 ENUM）+ directory_version（CHECK id=1，MySQL ≥ 8.0.16）
- 000007: plans 三行 seed + directory_version(1,1)，ON DUPLICATE KEY UPDATE 保可重入

所有表 ENGINE=InnoDB DEFAULT CHARSET=utf8mb4，时间列 DATETIME(6)，
主键 BIGINT UNSIGNED AUTO_INCREMENT + 对外 uuid CHAR(36) UNIQUE。
每对 down 文件逆序 DROP（子表先于父表）。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:28:01 +08:00
wangjia c92cd11cc5 feat: CI 流水线 — lint + 单测 + OpenAPI 校验 + 脱敏扫描 + 镜像构建 [tsk_P5b5nIrEsfrV] 
新增 .gitea/workflows/ci.yml 五个 Job：
  1. lint        — shellcheck -S warning 扫描全部 deploy/ shell 脚本
  2. unit-test   — docker-compose config 语法校验 + nginx -t（桩证书）
  3. openapi-check — openapi-spec-validator 验证 design/server/openapi.yaml
  4. redline-scan  — ci/scan-redline.sh 扫描 UI 文案红线词（design/ jsx/dart/html）
  5. image-build   — docker build pangolin-edge:ci

附带：
  - ci/scan-redline.sh：脱敏扫描脚本，过滤注释行与外部渠道 handle
  - ci/nginx-test.sh：自签桩证书 + nginx -t，CI 免依赖真实 Let's Encrypt
  - design/server/openapi.yaml：依据 ARCHITECTURE.md §3 展开的 OAS 3.0 完整契约
  - dparts.jsx / parts.jsx：修复 killSwitchSub EN 文案「the VPN drops」红线词
    → 改为「connection drops」（行为描述，不提产品类别）

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:19:28 +08:00
wangjia 20dbb5f363 feat(backup): 备份与灾备演练系统 [tsk_bYv-CoKSwgAC] 
实现 xtrabackup + binlog 增量备份、age 加密异地存储与月度 DR 演练。

## 交付内容

### deploy/backup/ —— 备份容器
- Dockerfile：Ubuntu 22.04 + xtrabackup 8.0 + age v1.2.0 + AWS CLI v2 + pg_client
- entrypoint.sh：初始化 AWS 凭据 / age 公钥，启动 crond
- crontab.txt：全量 02:00 / 增量每 15min / DR 演练每月 1 日
- scripts/lib.sh：日志 / age 加密 / S3 上传 / 连接测试等共用函数
- scripts/backup-full.sh：MySQL xtrabackup 全量 + pg_dump 全量 + SQLite 备份
- scripts/backup-inc.sh：MySQL xtrabackup 增量 + binlog flush & 归档 + pg_dump 快照
- scripts/restore.sh：从 S3 下载、解密、prepare / pg_restore 完整恢复
- scripts/dr-drill.sh：月度演练 —— RPO 验证 / 备份完整性 / MySQL 临时容器恢复 / RTO 度量
- scripts/verify-rpo-rto.sh：实时 RPO/RTO 状态检查（S3 最新备份时间戳）
- backup.env.example：配置模板（MySQL / PG / S3 / age 公钥）

### 修改已有文件
- deploy/docker-compose.yml：新增 pangolin-backup 服务
- deploy/scripts/gen-secrets.sh：幂等生成 age 密钥对 + backup.env 模板
- .gitignore：排除 age 私钥 / backup.env
- deploy/README.md：容器一览 + 备份快速命令

### docs/备份与灾备.md
S3 初始化、IAM 权限设计、age 密钥管理、MySQL 权限、DR 恢复步骤、RTO 测量标准

## 设计要点
- RPO ≤ 15min：每 15min xtrabackup 增量 + binlog flush + pg_dump 快照
- RTO ≤ 4h：月度演练度量，估算恢复时长约 2h
- 独立身份账号：备份 IAM 仅有 s3:PutObject，与生产账号完全隔离
- age 加密：公钥存服务器，私钥离线保存，S3 中无明文
- 无 crontab：cron 在容器内运行，绕过 ec2-user crontab 限制
- 幂等部署：backup.env 存在则跳过，age 密钥对存在则跳过

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-13 01:09:18 +08:00
wangjia a642bf16a2 feat: 同步 design/ 设计系统(含 iPad tablet kit) + 架构任务拆分(todo/) 
design/ 同步自最新设计导出，新增 ui_kits/tablet/ 平板分栏布局；todo/ 录入 18 个并行实施任务。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-06-11 23:57:57 +08:00
wangjia 3ae96ef229 docs: 新增整体架构设计文档(doc/，HTML 七章) 
覆盖前端五端/后端/MySQL/弹性节点拓扑/Web安全/安全总纲，遵循 design/ 设计系统视觉呈现。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-06-11 23:57:49 +08:00
wangjia 4bff8593e7 docs: 新增 CLAUDE.md(部署架构与主机约束指引) 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 23:30:08 +08:00
wangjia 73e026a4df edge 容器自带证书续期(certbot in nginx 镜像)
deploy-pangolin / deploy (push) Has been cancelled
Details 
- edge 改为自定义镜像:官方 nginx + certbot + dns-cloudflare 插件
- pangolin-entrypoint.sh:后台每12h certbot renew,续期后本容器内 nginx -s reload
- 不再需要宿主 cron / docker socket / 独立 certbot 服务做日常续期
- /etc/letsencrypt 改 rw 挂载,挂入 cloudflare.ini
- compose 去掉 build:(宿主 docker-compose 不支持 compose build),改脚本 docker build
- deploy.sh/cutover.sh: docker build -t pangolin-edge:local 后再 up

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 23:10:17 +08:00
wangjia 39e7f2fc11 回滚:rollback.sh + docs/回滚手册.md
deploy-pangolin / deploy (push) Has been cancelled
Details 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 17:09:00 +08:00
wangjia 1bb3a26f0c cutover: 失败自动回滚到宿主 nginx
deploy-pangolin / deploy (push) Has been cancelled
Details 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 16:52:05 +08:00
wangjia fa3954724c print-clients: 修正提示路径为 ~/pangolin
deploy-pangolin / deploy (push) Has been cancelled
Details 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 16:45:15 +08:00
wangjia 1a346c32c1 方案C:分发层容器化(edge nginx)+ Hy2 + DNS-01 续期
deploy-pangolin / deploy (push) Has been cancelled
Details 
- edge: 容器化 nginx 接管 80/443,逐字移植现网 vhost(blog/jiu/marzban/pay)+ stream SNI 分流
- singbox: Hysteria2(host 网络,UDP 443)
- certbot: DNS-01(Cloudflare)续期,容器化
- xray: REALITY 仅 profile newnode(本台沿用 Marzban)
- deploy.sh 幂等且切换感知;cutover.sh 一次性停宿主 nginx 切容器(可秒级回滚)
- 弃用方案A 的 host nginx-apply/sudoers/root-setup
- 部署目录改 ~/pangolin(免 root);CI 注入 CF_API_TOKEN

EC2 实测:edge nginx -t 通过(真实证书)、compose 校验通过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 16:42:30 +08:00
wangjia bc77e85b7d root-setup: 同时创建并授权 /opt/pangolin 部署目录
deploy-pangolin / deploy (push) Has been cancelled
Details 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
 2026-05-30 11:52:32 +08:00