在运行的系统上生长新功能

扩展的两条路

系统在运行，用户在使用。现在需要一个管理后台。

第一条路是重构。停下来，重新设计架构，统一新旧功能。这条路的诱惑在于"一次性解决所有问题"。但重构通常意味着风险集中，意味着长时间里用户看不到任何改进。

第二条路是生长。不碰核心，在边缘扩展。管理功能作为观察者和调节器附着在现有系统上，监测它，影响它，但不改变它的运行逻辑。

这不是妥协，而是理解：运行中的系统有它自己的平衡。打破这个平衡需要巨大的成本，而大部分时候，新功能并不需要这样的代价。

关键是依赖的方向：管理层依赖核心，核心不依赖管理层。这保证了即使管理功能全部失效，用户服务仍能正常运转。

权限的最小形态

管理后台需要权限控制。传统方案是建立 RBAC 系统：角色、权限、资源、操作，四个维度的组合。

但等等，真的需要这么复杂吗？

从实际需求倒推：有人需要看数据但不能改（观察者），有人需要操作用户和内容（管理员），有人需要完整控制权（超级管理员）。三个角色已经覆盖了所有场景。

不建新表，在现有 profiles 表上加一个字段：

ALTER TABLE profiles ADD COLUMN admin_role TEXT;
CREATE TYPE admin_role_enum AS ENUM ('viewer', 'admin', 'super_admin');

权限验证作为中间件，插入现有路由：

async function withAdminAuth(requiredRole = 'viewer') {
  const user = await getUser(token);
  if (!user.adminRole) throw new Error('Not admin');

  const roleLevel = { viewer: 1, admin: 2, super_admin: 3 };
  if (roleLevel[user.adminRole] < roleLevel[requiredRole]) {
    throw new Error('Insufficient permissions');
  }

  await next();
}

这个设计的本质：权限不是独立的系统，而是用户身份的扩展属性。

不需要额外查询，不需要复杂连表。普通用户的 admin_role 是 NULL，不影响现有逻辑。管理员的权限信息随用户信息一起读取，零额外开销。

数据的第二次使用

监控面板需要数据。最直接的想法是：建立新的监控表，定时采集系统指标，存储时间序列数据。

但系统已经在记录日志：任务执行记录、厂商健康检查、退款统计。这些表已经包含了监控需要的所有信息，只是之前没有界面展示。

关键洞见：监控不需要新的数据源，只需要新的查询方式。

-- 不建新表，只优化现有表的查询
CREATE INDEX idx_ai_generation_logs_event_time
  ON ai_generation_logs(event_type, created_at DESC);

-- 复杂聚合通过 RPC 函数实现
CREATE FUNCTION get_vendor_stats_7days()
RETURNS TABLE (vendor_id TEXT, error_rate NUMERIC) AS $$
  SELECT vendor_id,
    COUNT(CASE WHEN status = 'failed' THEN 1 END)::NUMERIC /
    NULLIF(COUNT(*), 0) AS error_rate
  FROM ai_generation_logs
  WHERE created_at >= NOW() - INTERVAL '7 days'
  GROUP BY vendor_id;
$$ LANGUAGE sql;

数据被使用了两次：第一次是业务逻辑记录日志，第二次是管理面板查询展示。没有重复存储，没有同步问题，没有额外成本。

这种设计的前提是：日志表记录了监控所需的维度。

完整的日志至少包含：状态（成功/失败）、时间戳（趋势分析）、关联ID（追踪上下文）、耗时（性能监控）。如果日志只记录成功不记录失败，错误率无法统计。如果日志不记录时间，趋势分析无法进行。如果日志不关联用户或任务ID，问题无法定位。

好的日志设计不只是为了当下的调试，而是为了未来可能的各种使用方式。相关思考见 调用链追踪的设计。

告警的克制艺术

Telegram 告警看起来简单：错误发生时发送消息。但这样的系统会迅速失控。

没有克制的告警系统会变成噪音制造机。同一个问题在五分钟内触发二十次告警，半夜被相同的错误消息轰炸。人会学会忽略告警，这比没有告警更危险。

关键是理解：不是所有错误都需要告警。

const alertRules = {
  highErrorRate: {
    threshold: 0.1,     // 10% 错误率才告警
    window: 300,        // 5分钟窗口
    cooldown: 1800      // 30分钟内不重复告警
  },
  vendorDown: {
    threshold: 3,       // 连续3次失败才告警
    cooldown: 3600      // 1小时冷却期
  }
};

冷却期（cooldown）是核心机制。它不是为了隐藏问题，而是为了保持告警的有效性。当你看到告警时，你知道：这是新问题，或者旧问题恶化了，需要立即处理。

告警的哲学：只告知需要人工介入的情况。

大部分错误应该由系统自动重试解决。只有重试失败，或者影响扩大到阈值以上，才需要通知人。错误是常态，告警应该是例外。

批量操作的边界

批量重试看起来高效：一次操作处理几十个失败任务。但批量操作很危险。

如果逻辑有问题，破坏也是批量的。一次操作影响一百个任务，如果失败，损失也是一百倍。

所以设计必须有严格的限制：

const LIMITS = {
  maxBatchSize: 50,      // 最多50个
  maxConcurrent: 10,     // 最多10个并发
  timeoutPerTask: 30000  // 每个30秒超时
};

这些数字从实际约束倒推：

批量上限50个：DLQ 中的任务通常不超过百个量级。50个能处理大部分场景（覆盖约50-80%的积压），但失败时影响可控。如果设100个，单次失败影响过大；如果设20个，处理效率太低，需要频繁操作。

并发限制10个：AI 厂商的速率限制通常是10-20 req/s。10个并发不会触发限流，同时保证批量操作不会瞬间产生流量尖峰。

超时30秒：单个 AI 任务正常耗时5-15秒，30秒超时能容忍网络波动，但避免慢任务阻塞整个批次。

关键原则：即使失败，也要能安全失败。

批量操作不应该全有或全无。处理50个任务，如果其中10个失败，应该返回详细结果：哪些成功了，哪些失败了，为什么失败。操作者可以根据结果决定下一步：是重试失败的，还是检查代码逻辑。

相关模式见 故障隔离的实现。

缓存的分层逻辑

管理查询可能很重：聚合大量日志，计算多维度统计。不能每次请求都执行，需要缓存。

但缓存不是简单的"存起来"。不同数据有不同的新鲜度要求。

class CacheManager {
  async get(key, fetcher, ttl) {
    // L1: 请求内存（毫秒级生命周期）
    if (this.memory[key]) return this.memory[key];

    // L2: KV 缓存（全球分布）
    const cached = await kv.get(key);
    if (cached && !isStale(cached, ttl)) {
      this.memory[key] = cached.data;
      return cached.data;
    }

    // L3: 数据源
    const data = await fetcher();
    await kv.put(key, data, { expirationTtl: ttl });
    this.memory[key] = data;
    return data;
  }
}

不同类型的数据，不同的 TTL：

• 用户信息：5分钟。用户的积分、权限变化不频繁，管理员查看时允许几分钟延迟。
• 任务统计：1分钟。反映当前系统负载，需要相对新鲜的数据，但不必秒级刷新。
• 历史趋势：1小时。过去一周的成本曲线，数据已固化，长缓存不影响准确性。

关键理解：管理后台通常不需要实时数据。

几分钟的延迟对大部分管理操作是可接受的。查看用户列表、分析成本趋势，这些场景不像用户下单那样要求毫秒级响应。这个认知让缓存策略变得简单：大胆地缓存，适当的 TTL，用性能换取开发复杂度的降低。

真正需要实时的场景（比如监控告警触发），通过 Supabase Realtime 绕过缓存直接推送。相关实现见 Redis 连接事件处理。

审计的静默记录

所有管理操作都需要记录，但记录不应该阻塞业务。

async function updateUserCredits(c, userId, credits) {
  // 获取原始数据
  const { data: oldProfile } = await supabase
    .from('profiles')
    .select('video_credits')
    .eq('id', userId)
    .single();

  // 业务操作
  const result = await supabase
    .from('profiles')
    .update({ video_credits: credits })
    .eq('id', userId);

  // 异步记录审计日志（不阻塞响应）
  c.executionCtx.waitUntil(
    logAdminAction({
      action: 'update_credits',
      resourceId: userId,
      changes: { from: oldProfile.video_credits, to: credits }
    })
  );

  return result;
}

审计日志的价值不在于实时性，而在于完整性。当你需要回溯某个操作时，信息就在那里。当日志写入失败时，业务操作不应该回滚。

这看起来不够严谨：如果日志失败了，操作就没有记录。但在实践中，这是正确的权衡。管理操作本身比它的记录更重要。如果因为日志系统故障导致操作失败，用户会更不满意。

关键是监控审计系统本身：如果日志写入持续失败，应该触发告警，而不是阻塞所有管理操作。

渐进的节奏

第一阶段构建基础：权限系统、核心 API、基本监控面板。完成后，系统可用。管理员能看到数据，能执行基本操作。

第二阶段增强能力：任务管理、告警系统、高级分析。完成后，运维效率显著提升。很多问题能自动发现，批量操作减少重复劳动。

第三阶段是规划中的智能化：基于历史数据的告警优化、预测性分析、自动化运维。但这些是未来的方向，不是当下的必需。

每个阶段都独立有价值。不是"完成全部才能用"，而是"每一步都让系统变得更好"。

这种节奏的本质：只做当下最需要的。

第二阶段的很多功能（批量重试、告警冷却期、成本分析）都是在第一阶段使用后才发现需要的。如果一开始就规划完整，可能会做很多最终用不到的功能。更糟的是，可能会误判优先级，先做不重要的，后做真正需要的。

软件是活的，需求是动态的。渐进式不是妥协，而是承认：我们无法预见所有需求，但可以快速响应真实需求。

相关方法论见 从意图到架构。

生长的本质

在运行的系统上构建管理层，核心不是技术选择，而是理解：

尊重边界。管理层观察和调节核心，但不改变核心逻辑。依赖是单向的。

复用数据。不建新表，不建新的数据管道。在现有数据上找到新的查询方式。

克制告警。只告警需要人工介入的情况。保持信噪比，而不是记录所有异常。

限制批量。批量操作有明确上限。限制不是妥协，而是安全失败的保障。

分层缓存。不同数据有不同的新鲜度要求。管理后台不需要实时数据。

静默审计。记录不阻塞业务。监控审计系统本身，而不是让它阻止业务操作。

渐进节奏。每个迭代独立有价值。在使用中发现下一步需求，而不是预见完美。

Purikura 的 CMS 系统不是一次性设计出来的，而是在生产环境中生长出来的。它从最小的权限验证开始，逐步加入监控、告警、分析。每一步都解决了真实的问题，每一步都建立在前一步的基础上。

这才是扩展的真实样子：不是推倒重来，而是理解边界，找到生长点，让新功能自然地附着在旧系统上。