wangjia
bbe149fd41
P0:控制面明文 HTTP、SQLite 零备份。P1:同机换账号设备注册 403 死结(migration16 注释里推迟的 UNIQUE(user_id,uuid) 未落地)、disconnect 撤账户级凭证而 connect 发 每设备凭证、agent 用量 Reset 后上报失败即丢(at-most-once)、Redis 白名单单点全员 掉线、argon2id 64MiB 并发 OOM。P2:sessions/audit 无留存、免费额度 UTC 日界、 三时钟口径、hub 内存态、单实例端口无握手、ReportUsage 无事务。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
197 lines
14 KiB
HTML
197 lines
14 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Pangolin 文档索引</title>
|
||
<style>
|
||
:root{
|
||
--bg:#0f1117; --panel:#171a22; --panel2:#1d2129; --fg:#e6e8ee; --fg2:#a8afbd;
|
||
--accent:#e0884f; --accent2:#5fb0c9; --ok:#5ec27a; --bad:#e06a6a; --warn:#e0b84f;
|
||
--border:#272c36; --mono:"SF Mono",ui-monospace,Menlo,Consolas,monospace;
|
||
--sans:-apple-system,"PingFang SC","Helvetica Neue",Arial,sans-serif;
|
||
}
|
||
*{box-sizing:border-box}
|
||
body{margin:0;background:var(--bg);color:var(--fg);font-family:var(--sans);line-height:1.7;font-size:15px}
|
||
.wrap{max-width:920px;margin:0 auto;padding:48px 24px 96px}
|
||
h1{font-size:30px;line-height:1.3;margin:0 0 8px;letter-spacing:-.01em}
|
||
.sub{color:var(--fg2);font-size:15px;margin:0 0 32px}
|
||
h2{font-size:21px;margin:40px 0 14px;padding-bottom:8px;border-bottom:1px solid var(--border)}
|
||
p{margin:10px 0}
|
||
code{font-family:var(--mono);font-size:.88em;background:var(--panel2);padding:1px 6px;border-radius:5px;color:#f0d9c4}
|
||
a{color:var(--accent2);text-decoration:none}
|
||
a:hover{text-decoration:underline}
|
||
.lead{background:linear-gradient(180deg,rgba(224,136,79,.10),transparent);border:1px solid var(--border);border-radius:12px;padding:18px 20px;margin:0 0 8px}
|
||
.small{color:var(--fg2);font-size:13px}
|
||
.tag{display:inline-block;font-size:11px;font-weight:700;padding:1px 8px;border-radius:999px;vertical-align:middle;margin-left:6px}
|
||
.tag.html{background:rgba(94,194,122,.16);color:var(--ok)}
|
||
.tag.md{background:rgba(168,175,189,.16);color:var(--fg2)}
|
||
.doc{display:block;background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:14px 16px;margin:10px 0;transition:border-color .15s}
|
||
.doc:hover{border-color:var(--accent2);text-decoration:none}
|
||
.doc .t{font-size:16px;font-weight:600;color:var(--fg)}
|
||
.doc .d{color:var(--fg2);font-size:13px;margin-top:3px}
|
||
.doc .path{font-family:var(--mono);font-size:11px;color:#6b7385;margin-top:4px}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="wrap">
|
||
|
||
<h1>Pangolin 文档索引</h1>
|
||
<p class="sub">全部设计 / 调研 / 排障文档汇总 · 单一入口</p>
|
||
|
||
<div class="lead">
|
||
<strong>约定：</strong>新的<b>设计文档 / 调研文档</b>统一以 <b>HTML</b> 形式输出（深色家族风格，可直接 <code>file://</code> 打开），并登记到本索引。历史 <code>.md</code> 文档保留原状、逐步迁移。
|
||
</div>
|
||
|
||
<h2>设计方案 / Specs</h2>
|
||
<a class="doc" href="contact-telegram-channels-design.html">
|
||
<div class="t">联系我们 · 渠道二级页（Telegram 频道/群组，DB 配置）<span class="tag html">HTML</span></div>
|
||
<div class="d">点 Telegram 进二级页，按 kind 分组（频道/群组/Bot）列多条链接，含 @handle/说明/认证/「打开·加入」动作，全渠道（含邮箱/发卡）统一一张 contact_link 表（靠 url 协议区分 mailto/https/tg）。独立 GET /v1/contact。规则：平台 >1 条链接才进二级，否则点击直达。LINE 同构但先灰置「即将开放」（registry comingSoon 开关，配好即去灰）。不展示成员数、群组=加入。含可点原型。</div>
|
||
<div class="path">docs/contact-telegram-channels-design.html</div>
|
||
</a>
|
||
<a class="doc" href="free-quota-ad.html">
|
||
<div class="t">免费版 10 分钟卡控 + 累加式看广告加时 <span class="tag html">HTML</span></div>
|
||
<div class="d">免费版真卡控（账户级/全设备共享）：连接期倒计时 + 到点自动切断 + 耗尽按钮灰化 + 点击弹广告看完 +10 分钟（累加，每日封顶 120）。桌面硬 10 分钟不可延。服务端 ad_bonus_minutes 累加模型 + ConnectNode 按 remaining 卡控 + TTL 硬切断；占位 DevVerifier。#21。</div>
|
||
<div class="path">docs/free-quota-ad.html</div>
|
||
</a>
|
||
<a class="doc" href="device-limit-design.html">
|
||
<div class="t">设备数量限制 + 超限 UX <span class="tag html">HTML</span></div>
|
||
<div class="d">真正启用套餐设备上限（free 1 / pro 3 / team 10）：卡在登录（非硬拒登，返回 device_limit 信号）+ 选择移除/一键踢最旧 + 服务端按 last_seen 自动清理久不活跃。复用现成 DeleteDevice/ResolvePlan。无 DB schema 变更。#16。</div>
|
||
<div class="path">docs/device-limit-design.html</div>
|
||
</a>
|
||
<a class="doc" href="device-session-management-design.html">
|
||
<div class="t">设备 & 会话管理 + 每设备流量归因 <span class="tag html">HTML</span></div>
|
||
<div class="d">「我的设备」管理（名称/平台/客户端版本/在线/最后登录 + 强制退出/清除登录信息）+ 控制面 sessions 表绑设备 + 数据面每设备 dp_uuid 记账。核心洞察：后端大半已建但 RegisterIfAbsent 未接线致 devices 表空。P1–P5 路线。</div>
|
||
<div class="path">docs/device-session-management-design.html</div>
|
||
</a>
|
||
<a class="doc" href="android-client-design.html">
|
||
<div class="t">Pangolin Android 客户端设计方案 <span class="tag html">HTML</span></div>
|
||
<div class="d">把 M2 纸面 PoC 推到真机端到端连通 + 切节点 + KillSwitch（清 TODO 11G）。里程碑 A–F、三处定调。</div>
|
||
<div class="path">docs/android-client-design.html</div>
|
||
</a>
|
||
<a class="doc" href="ios-ipad-support-design.html">
|
||
<div class="t">iOS + iPad 支持设计方案 <span class="tag html">HTML</span></div>
|
||
<div class="d">iOS 隧道从 PoC 桩推到真机连通 + TestFlight；五条工作线 + NE 50MB 内存闸门；iPad 横屏侧栏布局适配。</div>
|
||
<div class="path">docs/ios-ipad-support-design.html</div>
|
||
</a>
|
||
<a class="doc" href="superpowers/specs/2026-06-21-windows-client-design.md">
|
||
<div class="t">Windows 客户端设计 <span class="tag md">MD</span></div>
|
||
<div class="d">Windows 端 sing-box 子进程 + wintun 隧道客户端设计。</div>
|
||
<div class="path">docs/superpowers/specs/2026-06-21-windows-client-design.md</div>
|
||
</a>
|
||
|
||
<h2>实现计划 / Plans</h2>
|
||
<a class="doc" href="device-session-management-plan.html">
|
||
<div class="t">设备 & 会话管理 + 每设备流量归因 实现计划（P1–P6）<span class="tag html">HTML</span></div>
|
||
<div class="d">阅读版；执行真相源为 <code>docs/superpowers/plans/2026-06-29-device-session-management.md</code>（含 checkbox）。P1 设备注册打通 → P2 sessions表+在线/最后登录 → P3 强制退出/清除 → P4 每设备流量 → P5 2FA信任(future) → P6 UI重做。</div>
|
||
<div class="path">docs/device-session-management-plan.html</div>
|
||
</a>
|
||
<a class="doc" href="superpowers/plans/2026-06-22-android-client.md">
|
||
<div class="t">Android 客户端实现计划 <span class="tag md">MD</span></div>
|
||
<div class="d">11 个任务：Go 1.24.3 工具链 → 构建 libbox.aar → 解析真实 API → Dart 接线 → 修原生编译 → 模拟器端到端 → 统计 → 切节点 → KillSwitch → 真机验证。</div>
|
||
<div class="path">docs/superpowers/plans/2026-06-22-android-client.md</div>
|
||
</a>
|
||
<a class="doc" href="ios-ipad-support-plan.html">
|
||
<div class="t">iOS + iPad 支持 实现计划 <span class="tag html">HTML</span></div>
|
||
<div class="d">阅读版；执行真相源为 <code>docs/superpowers/plans/2026-06-22-ios-ipad-support.md</code>（含 checkbox）。6 阶段 12 任务。</div>
|
||
<div class="path">docs/ios-ipad-support-plan.html</div>
|
||
</a>
|
||
<a class="doc" href="superpowers/plans/2026-06-21-windows-client.md">
|
||
<div class="t">Windows 客户端实现计划 <span class="tag md">MD</span></div>
|
||
<div class="d">Windows 客户端的分步实现计划。</div>
|
||
<div class="path">docs/superpowers/plans/2026-06-21-windows-client.md</div>
|
||
</a>
|
||
<a class="doc" href="stats-overhaul-plan.html">
|
||
<div class="t">统计体系整改 实现计划（#5）<span class="tag html">HTML</span></div>
|
||
<div class="d">阅读版；执行真相源为 <code>docs/superpowers/plans/2026-06-24-stats-overhaul.md</code>（含 checkbox）。三期：四端实时统计修复 → 每设备归因+GB综合配额 → 统计页重设计(上聚合·下分设备)。</div>
|
||
<div class="path">docs/stats-overhaul-plan.html</div>
|
||
</a>
|
||
|
||
<h2>知识库 / 调研</h2>
|
||
<a class="doc" href="code-review-2026-07.html">
|
||
<div class="t">全栈设计审查 2026-07（前端/后端/数据库）<span class="tag html">HTML</span></div>
|
||
<div class="d">核心链路精读式审查，13 项发现分 P0/P1/P2：明文 HTTP、SQLite 零备份（P0）；同机换账号 403 死结、disconnect 撤错凭证、用量取走即焚、Redis 重启全员掉线、argon2id OOM（P1）；留存/UTC 日界/三时钟口径等（P2）。附「做得好的」与处理顺序建议。</div>
|
||
<div class="path">docs/code-review-2026-07.html</div>
|
||
</a>
|
||
<a class="doc" href="dev-conventions.html">
|
||
<div class="t">开发规范 · 可测试性五支柱 <span class="tag html">HTML</span></div>
|
||
<div class="d">「怎么写才好测」——开发规范作为可测试性前置条件。五支柱（接缝即接口/契约单源/纯逻辑分离/错误是值/可观测）+ 支柱↔测试层咬合矩阵图 + 反例→真实bug→对应支柱对照表。与测试框架文档咬合。</div>
|
||
<div class="path">docs/dev-conventions.html</div>
|
||
</a>
|
||
<a class="doc" href="test-architecture.html">
|
||
<div class="t">统一测试框架 · 架构说明 <span class="tag html">HTML</span></div>
|
||
<div class="d">多端项目可复用的分层测试方法论（L0 契约→L4 E2E）+ 四类诉求(界面一致/交互/数值/后端记账)→层→工具→量化指标映射 + 五张架构图（金字塔/契约接缝/CI 流水线/E2E 拓扑）+ ⑩「已知缺口/测试盲区」单一跟踪源（没测什么·为什么·何时补）。</div>
|
||
<div class="path">docs/test-architecture.html</div>
|
||
</a>
|
||
<a class="doc" href="feature-test-coverage-checklist.html">
|
||
<div class="t">功能 × 测试覆盖清单 <span class="tag html">HTML</span></div>
|
||
<div class="d">逐功能盘点验证五端是否正确：A 共享逻辑+后端(控制面 21 包/数据面渲染+记账/Flutter 共享)，每行「现有能力→已覆盖+怎么覆盖→欠缺→只能人工」；B 平台隧道层五端矩阵 + 每端真连通验收清单(出口IP变化/DNS劫持/分流/记账对账/KillSwitch/切节点)。配套 test-architecture.html 的「逐功能」视角。</div>
|
||
<div class="path">docs/feature-test-coverage-checklist.html</div>
|
||
</a>
|
||
<a class="doc" href="traffic-accounting-scopes.html">
|
||
<div class="t">流量记账口径 · 连接页实时 vs 统计页累计 <span class="tag html">HTML</span></div>
|
||
<div class="d">客户端两处"上传/下载"为何对不上：连接页实时来自内核 Clash API 全局吞吐(/traffic+/connections)<b>含直连</b>；统计页累计来自服务端节点 v2ray_api per-user 计数<b>仅代理</b>。差额=直连流量(国内站/分流)，设计使然非 bug；附对账口径警示(不能拿连接页含直连的数去对节点计数)。</div>
|
||
<div class="path">docs/traffic-accounting-scopes.html</div>
|
||
</a>
|
||
<a class="doc" href="killswitch-design.html">
|
||
<div class="t">KillSwitch 设计与跨平台能力矩阵 <span class="tag html">HTML</span></div>
|
||
<div class="d">断网保护 L0–L3 分级模型 + 各平台能力天花板 / 当前实现矩阵。KillSwitch 决策依据。</div>
|
||
<div class="path">docs/killswitch-design.html</div>
|
||
</a>
|
||
<a class="doc" href="技术方案.md">
|
||
<div class="t">技术方案（总） <span class="tag md">MD</span></div>
|
||
<div class="d">Pangolin 整体技术选型与架构方案。</div>
|
||
<div class="path">docs/技术方案.md</div>
|
||
</a>
|
||
<a class="doc" href="vpn-core-embedding.md">
|
||
<div class="t">VPN 内核内嵌 <span class="tag md">MD</span></div>
|
||
<div class="d">sing-box 内核在各端的内嵌方式调研。</div>
|
||
<div class="path">docs/vpn-core-embedding.md</div>
|
||
</a>
|
||
<a class="doc" href="vpn-testing-research.md">
|
||
<div class="t">VPN 测试调研 <span class="tag md">MD</span></div>
|
||
<div class="d">VPN 黑盒测试方法与口径调研。</div>
|
||
<div class="path">docs/vpn-testing-research.md</div>
|
||
</a>
|
||
<a class="doc" href="vpn-test-plan.md">
|
||
<div class="t">VPN 测试计划 <span class="tag md">MD</span></div>
|
||
<div class="d">国内外站点矩阵 + 延迟/连通性测试计划。</div>
|
||
<div class="path">docs/vpn-test-plan.md</div>
|
||
</a>
|
||
|
||
<h2>排障 / Runbook</h2>
|
||
<a class="doc" href="connect-latency-urltest.html">
|
||
<div class="t">连接页延迟(urltest)· 跨端实现 + 排障 <span class="tag html">HTML</span></div>
|
||
<div class="d">连接页"延迟"= 内核 urltest(非直连实测)。根因链:服务端配置无 clash_api、libbox 单 client Group 不回调、Dart 广播流抢 EventChannel sink、连接态直连实测假值。各端(macOS/iOS/Android/Windows)注入 clash_api + 本地 HTTP 取法 + 排障打点 + libbox 构建前置(Android 要 JDK 17、包名 io.nekohasekai.libbox)。</div>
|
||
<div class="path">docs/connect-latency-urltest.html</div>
|
||
</a>
|
||
<a class="doc" href="ci-runner.md">
|
||
<div class="t">CI Runner 设置记录 <span class="tag md">MD</span></div>
|
||
<div class="d">gitea Actions self-hosted runner 记录:决定用 1 个(mac-pangolin-2,项目级·mac host·label nas·复用 jiu relay)、已删 orphan 的清理命令、launchd 持久化 + 单点韧性(runner 离线 Telegram 告警)。CI 首跑 run #298。</div>
|
||
<div class="path">docs/ci-runner.md</div>
|
||
</a>
|
||
<a class="doc" href="macos-sysext-realize-troubleshooting.html">
|
||
<div class="t">macOS 系统扩展 realize 失败（code=4）踩坑复盘 <span class="tag html">HTML</span></div>
|
||
<div class="d">PacketTunnel 系统扩展无法激活的三个叠加配置 bug 排查与修复。</div>
|
||
<div class="path">docs/macos-sysext-realize-troubleshooting.html</div>
|
||
</a>
|
||
<a class="doc" href="p1-macos-system-extension.md">
|
||
<div class="t">P1 macOS 系统扩展 <span class="tag md">MD</span></div>
|
||
<div class="d">macOS 原生 System Extension 隧道方案说明。</div>
|
||
<div class="path">docs/p1-macos-system-extension.md</div>
|
||
</a>
|
||
<a class="doc" href="node-rebuild-checklist.md">
|
||
<div class="t">节点重建检查单 <span class="tag md">MD</span></div>
|
||
<div class="d">节点重装/重建的操作检查清单。</div>
|
||
<div class="path">docs/node-rebuild-checklist.md</div>
|
||
</a>
|
||
<a class="doc" href="runbook-scheduler.md">
|
||
<div class="t">Scheduler Runbook <span class="tag md">MD</span></div>
|
||
<div class="d">调度器运维手册。</div>
|
||
<div class="path">docs/runbook-scheduler.md</div>
|
||
</a>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|