Files
LFSpecs/DESIGN.md
T

36 KiB
Raw Blame History

LFSpecs 设计稿(v0.2)

公开硬件规格库。收录手机、平板、电脑、SoC/CPU/GPU、外设等设备配置,页面只读展示,编辑需简单验证,AI 辅助补全参数。 本文档是设计稿,已确认的决策见第 11 节。


1. 一句话定位

一个公开的硬件规格数据库:像产品库一样浏览任何设备的详细参数,像编辑器一样低成本录入,像 Git 仓库一样可靠备份。

不是"我的设备清单",是"设备参数百科"——收录的是产品型号,不是某个人的资产。因此不记录购入价格、购买渠道、个人持有状态、使用心得。

目标

  • 录入快:给个型号,AI 把参数表填好并按置信度分级,人只核对低置信度部分。
  • 参数全:细到摄像头传感器型号、振动马达型号、扬声器单元规格。
  • 浏览爽:分类、品牌、搜索、筛选、多设备横向对比,手机端也能看。
  • 运维轻:单机/单容器可跑,数据是几个文件,拷走即迁移。
  • 只读安全:访客看不到任何编辑入口,写操作必须过一道验证。

非目标(明确不做)

  • 不做多用户注册体系 / 权限角色矩阵(只有一个"站主"身份)。
  • 不做社区、评论、点赞、投稿。
  • 不做实时价格抓取、电商比价(AI 查询是"补参数",不是"追价格")。
  • 不做个人资产台账(无购入价、无保修期、无转卖记录)。

2. 技术选型

层 选择 理由
框架 Astro 5 默认零 JS、内容型站点最优;需要交互时用 islands 局部加载;内置图片优化、View Transitions
样式 Tailwind CSS 4 与 shadcn 生态绑定,v4 走 @tailwindcss/vite 插件,无需 config 文件
组件 shadcn/ui 注意:它是 React 组件库,Astro 下需 @astrojs/react 集成,以 island 形式使用;纯展示区域仍可写 .astro 组件
校验 Zod 数据模型单一事实来源,表单、API、导入导出、AI 输出全部复用同一套 schema
动效 Motion (原 framer-motion) + Astro View Transitions 见第 7 节
数据库 SQLite(方案 A,见第 4 节) 单文件、零运维、备份即拷贝;实现用 Node 内置 node:sqlite,无原生编译依赖
存储 本地磁盘 + S3 兼容(双驱动,见 9.1) 先本地跑通,需要时一键切对象存储
语言 TypeScript strict —
包管理 pnpm —

需要提前踩的点

  • shadcn/ui 在 Astro 中是"部分适配":npx shadcn@latest init 需选 Astro 选项(依赖 React 集成)。如果发现处处别扭,备选是只借它的设计 token + Radix 无样式组件,自己写 Astro 包装,或改用纯 Tailwind 手写组件。建议先做一个 3 个组件的 PoC 验证,再决定全量采用。
  • Tailwind v4 的 @theme 写法与 shadcn 旧版 HSL 变量不同,初始化时注意版本一致。

3. 页面与功能

3.1 路由

/                       首页:分类入口 + 最新收录 + 热门对比
/devices                设备列表(分类 Tab + 品牌筛选 + 搜索 + 排序)
/devices/[slug]         设备详情:主图 + 关键参数网格 + 分组规格表 + 关联芯片 + 图库
/brands                  品牌索引
/brands/[brand]         品牌下全部产品
/chips                  芯片库(SoC / CPU / GPU / NPU / 模组)
/chips/[slug]           芯片详情 + "搭载该芯片的设备"反查列表
/peripherals            外设列表(显示器/键鼠/耳机/存储/网络/掌机配件)
/compare?ids=a,b,c      横向对比(2–4 个,同类别限定,差异高亮)
/admin                  登录入口
/admin/devices/[slug]   编辑表单
/admin/import           批量导入导出
/api/*                  写接口、AI 接口、导出接口

已去掉 /timeline(个人时间线属于私人内容),改为 /brands 索引,更符合公开数据库的浏览路径。

3.2 详情页信息布局(以手机为例)

  • 头部:品牌 / 型号 / 别名 / 发布与上市日期 / 生命周期徽章(已发布·在售·停产)/ 封面图
  • 关键参数卡(6–8 个最重要项,大字号):SoC、屏幕、电池、主摄、重量、存储
  • 分组规格表:外观 / 屏幕 / 平台 / 内存存储 / 后置影像 / 前置影像 / 音频与震动 / 连接 / 电池充电 / 传感器 / 系统
  • 关联:同 SoC 的其他机型、同代竞品入口(一键加入对比)
  • 底部:数据来源与更新时间、字段级置信度说明

3.3 对比页设计要点

  • 入口:列表勾选 / 详情页"加入对比"浮动条 / 直接拼 URL
  • 顶部设备头图错位排列,便于识别
  • 表格:首列字段名粘性,横向滚动;移动端可左右滑动查看设备
  • 开关:只看差异、分组折叠
  • 值对齐:数值化拆分(6.79 英寸 → 6.79 + 单位),支持条形长度可视化(电池容量、屏幕亮度、重量)
  • 同类别才能对比(手机 vs 手机、显卡 vs 显卡),跨类别给出提示

3.4 增强想法(可后置)

  • 自动 OG 图:每台设备生成分享卡片(satori / @vercel/og)
  • 雷达图:屏幕/性能/续航归一化评分可视化
  • 结构化数据:每页输出 Product JSON-LD,利于搜索引擎收录(公开站必备)
  • sitemap + RSS:新收录设备可订阅
  • 完整性提示:后台将"缺关键字段"的设备标黄,引导补全
  • 打印样式:详情页可导出为干净的 PDF 规格表
  • Changelog:每次编辑生成一条记录,公开可见(体现数据可追溯)

4. 数据层:三套方案(关键决策)

这是整个项目最需要先定的事,因为它决定部署方式、备份方式、编辑方式。

✅ 方案 A:Astro SSR + SQLite(已采纳)

  • 部署:@astrojs/node adapter,Docker 单容器;数据 = data/app.db + data/uploads/,挂载卷。
  • 备份:scripts/backup.sh 执行 sqlite3 .backup + 打包 uploads → 一个 .tar.gz。
  • 迁移:换机器 = 拷目录 + 起容器。
  • 编辑:/admin 表单直接写库,密码 cookie 会话。
  • 优点:网页端可编辑;单文件备份;无外部依赖。
  • 缺点:需要一台长期在线的机器(VPS / NAS / 树莓派);SQLite 单写入者,够用但不适合高并发。

方案 B:纯静态 + 数据即仓库(最轻运维)

  • 数据存 src/content/devices/*.md(x) 或 data/*.json,走 Astro Content Collections + zod。
  • 部署:任意静态托管(Cloudflare Pages / GitHub Pages / 对象存储 / NAS 静态目录)。
  • 备份:Git 仓库本身就是备份与版本历史,零成本。
  • 编辑:本地 pnpm admin 起一个仅本机可访问的编辑表单,保存后自动 git commit;或直接改 JSON + VS Code。
  • 优点:部署最快、成本≈0、天然版本管理、迁移=clone。
  • 缺点:网页端不能改(除非引入 Decap CMS/TinaCMS,那又需要一个 Git 网关/服务)。

方案 C:静态 + Cloudflare D1/R2 + Workers 写接口

  • 页面静态化,写操作走 Worker + 密码;图片进 R2。
  • 优点:零运维、全球加速、免费额度够个人用。
  • 缺点:数据落在 Cloudflare,备份靠 d1 export(能做,但迁移到非 CF 环境要多一步)。

结论(已确认)

采纳 方案 A:VPS/NAS 上 Docker 单容器,Astro SSR(@astrojs/node)+ SQLite,浏览器内直接编辑。

  • 数据访问仍收敛到单一 repository 层(src/lib/repo.ts 暴露 listDevices/getDevice/saveDevice/...),未来若想迁到 B/C 只改这一层。
  • 保留 B/C 的价值:A 必须能导出一份完整 JSON,这样随时可以降级为静态站(导出 → 生成 content collection → 静态构建)。这个导出能力不是可选项,是方案 A 的逃生舱。

4.1 目录结构

LFSpecs/
├─ src/
│  ├─ pages/
│  │  ├─ index.astro
│  │  ├─ devices/index.astro · [slug].astro
│  │  ├─ chips/index.astro · [slug].astro
│  │  ├─ peripherals/index.astro
│  │  ├─ compare.astro
│  │  ├─ timeline.astro
│  │  ├─ admin/…(login / devices/[slug] / import)
│  │  └─ api/(auth, devices, ai, export, import)
│  ├─ components/          # .astro 为主,交互的才用 .tsx
│  ├─ lib/
│  │  ├─ repo.ts           # 唯一数据出入口
│  │  ├─ db.ts             # sqlite 连接 + 迁移
│  │  ├─ schema/           # zod:device / chip / specs 各分类 + FieldMeta
│  │  ├─ storage.ts        # 图片存储抽象(local / s3)
│  │  ├─ ai/               # provider 抽象 + prompt + 结果校验
│  │  └─ auth.ts           # 签发/校验 cookie
│  ├─ content/             # 可选:markdown 长文
│  └─ styles/
├─ data/                   # 运行时数据(不进 git)
│  ├─ app.db
│  └─ uploads/
├─ scripts/backup.ts
├─ migrations/
├─ Dockerfile
└─ docker-compose.yml

4.2 表结构(SQLite)

CREATE TABLE devices (
  id            INTEGER PRIMARY KEY,
  slug          TEXT UNIQUE NOT NULL,
  category      TEXT NOT NULL,          -- phone/tablet/laptop/desktop/handheld/peripheral
  sub_category  TEXT,                   -- 外设细分:monitor/keyboard/mouse/...
  brand         TEXT NOT NULL,
  model         TEXT NOT NULL,
  aliases_json  TEXT DEFAULT '[]',      -- 别名 / 地区型号,参与搜索
  announce_date TEXT,
  release_date  TEXT,
  lifecycle     TEXT NOT NULL DEFAULT 'released',  -- announced/released/discontinued
  cover_key     TEXT,                   -- 存储 key,不是 URL
  gallery_json  TEXT DEFAULT '[]',      -- 存储 key 数组
  tags_json     TEXT DEFAULT '[]',
  summary       TEXT,                   -- 客观简介
  specs_json    TEXT NOT NULL,          -- 分类规格,zod 校验后写入
  chip_refs_json TEXT DEFAULT '{}',     -- {soc,cpu,gpu,npu,modem} -> chip.slug
  meta_json     TEXT DEFAULT '[]',      -- FieldMeta[]:字段级置信度与来源
  created_at    TEXT NOT NULL,
  updated_at    TEXT NOT NULL
);

CREATE TABLE chips (
  id INTEGER PRIMARY KEY,
  slug TEXT UNIQUE NOT NULL, type TEXT NOT NULL,   -- soc/cpu/gpu/npu/modem
  brand TEXT, model TEXT NOT NULL, codename TEXT,
  aliases_json TEXT DEFAULT '[]',
  process TEXT, arch TEXT,
  detail_json TEXT NOT NULL,            -- 核心簇/显存/跑分等,结构随 type 变化
  meta_json TEXT DEFAULT '[]',
  created_at TEXT, updated_at TEXT
);

CREATE TABLE revisions (               -- 每次保存一条,用于回滚与 changelog
  id INTEGER PRIMARY KEY,
  entity TEXT NOT NULL,                -- 'device' | 'chip'
  entity_id INTEGER NOT NULL,
  snapshot_json TEXT NOT NULL,         -- 保存后的完整态
  diff_json TEXT,                      -- 与上版差异,便于展示
  created_at TEXT NOT NULL
);

CREATE TABLE ai_cache (                -- 省钱用
  key TEXT PRIMARY KEY,                -- category|brand|model
  result_json TEXT NOT NULL,
  sources_json TEXT, created_at TEXT NOT NULL
);

CREATE TABLE ai_drafts (               -- AI 结果先进草稿态,人工确认后才 merge
  id INTEGER PRIMARY KEY, device_id INTEGER,
  payload_json TEXT NOT NULL, sources_json TEXT,
  status TEXT NOT NULL DEFAULT 'pending', created_at TEXT
);

CREATE INDEX idx_devices_cat ON devices(category);
CREATE INDEX idx_devices_brand ON devices(brand);
CREATE INDEX idx_chips_type ON chips(type);

specs_json 用 JSON 列而非拆表:参数随代际变化大,拆表会陷入持续迁移。json_extract 足够应付筛选(如 WHERE json_extract(specs_json,'$.display.refreshRate') >= 120)。筛选需求变重时再加 spec_index 辅助表,把热门可筛字段(刷新率/容量/尺寸/重量)打平。

4.3 部署产物

# docker-compose.yml
services:
  app:
    build: .
    ports: ["3000:3000"]
    volumes: ["./data:/app/data"]
    environment:
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      SESSION_SECRET: ${SESSION_SECRET}
      AI_BASE_URL: ${AI_BASE_URL}
      AI_API_KEY: ${AI_API_KEY}
      AI_MODEL: ${AI_MODEL}
      SEARCH_API_KEY: ${SEARCH_API_KEY}
      STORAGE_DRIVER: ${STORAGE_DRIVER}     # local | s3
      # s3 时追加:S3_ENDPOINT / S3_BUCKET / S3_REGION / S3_KEY / S3_SECRET / S3_PUBLIC_BASE_URL

迁移到新机器:tar 打包 data/ → 拷贝 → docker compose up -d。


5. 数据模型

5.1 设计取向

公开规格库的核心诉求是可比,所以:

  • 强模板 + 可扩展:每个 category 一套 zod schema 定义核心字段(保证任意两台同类设备都能逐行对齐),另留 extra: Record<string,string> 收纳长尾参数。不再"弱 schema"——对比页依赖字段一致性。
  • 字段级元数据:每个值都能携带 confidence / sourceUrl / verified / capturedAt。这是 AI 分级录入的基础,也是公开展示"数据可信度"的依据。
  • 产品导向:只记录产品客观参数,不含购入价、个人评价、持有状态。

5.2 实体

Device(设备) — 手机、平板、笔记本、台式机、掌机、外设统一入口,用 category 区分。

Device {
  id, slug
  category: 'phone' | 'tablet' | 'laptop' | 'desktop' | 'handheld' | 'peripheral'
  subCategory?                 // 外设细分:monitor/keyboard/mouse/headset/storage/network
  brand, model
  aliases: string[]            // 别名、地区型号(如 "Xiaomi 14 / 小米14")
  announceDate?, releaseDate?
  lifecycle: 'announced' | 'released' | 'discontinued'
  cover?, gallery: string[]    // 存 storage key,不是绝对 URL
  tags: string[]
  summary?                     // 客观简介(AI 可生成,人工可改)
  specs: PhoneSpecs | LaptopSpecs | DesktopSpecs | GpuSpecs | ...
  chipRefs: { soc?, cpu?, gpu?, npu?, modem? }   // -> Chip.slug
  meta: FieldMeta[]            // 字段级来源与置信度
  createdAt, updatedAt
}

Chip(芯片) — 独立实体,设备通过 chipRefs 引用,支持反查"搭载该芯片的机型"。

Chip {
  id, slug
  type: 'soc' | 'cpu' | 'gpu' | 'npu' | 'modem'
  brand, model, codename?, aliases: string[]
  process: string              // "TSMC N4P"
  arch: string                 // "ARMv9.2" / "Zen 5" / "Blackwell"
  // SoC 专属
  cpuClusters?: { name, cores: { microArch, count, clockMax, l1, l2 }[], l3 }[]
  gpuBlock?: { name, arch, cores, clockMax, apis[] }
  npuBlock?: { name, tops? }
  ispBlock?, dspBlock?, modemBlock?
  memorySupport?, storageSupport?, displaySupport?, videoCodec?
  // CPU / GPU 专属
  cores?, threads?, clocks?, cache?
  smCount?, rtCores?, tensorCores?
  memory?: { type, capacity, busWidth, bandwidth }
  tdp?, pcie?, powerConnectors?
  benchmarks: { name, score, unit }[]
  features: string[]
  meta: FieldMeta[]
  createdAt, updatedAt
}

FieldMeta(字段元数据) — 与 AI 分级机制配套。

FieldMeta {
  path: string                 // "specs.rearCamera[0].sensorModel"
  confidence: 'high' | 'medium' | 'low'
  sourceUrl?: string
  verified: boolean            // 人工确认过
  capturedAt: string
}

Revision / ai_cache / ai_drafts — 与 4.2 节的表一致。

5.3 手机规格模板(细化版)

PhoneSpecs {
  body: {
    dimensions, weight, build: { front, back, frame },
    sim, ipRating, colors[], buttons
  }
  display: {
    size, resolution, aspectRatio, panel,
    refreshRate, refreshRange,          // "1-120Hz"
    touchSampling, brightnessTypical, brightnessPeak,
    hdr, protection,                    // "康宁大猩猩 Victus 2"
    pwmDimming,                         // "2160Hz PWM"
    alwaysOn
  }
  platform: { os, skin, chipset }
  memory: { ram, ramType, storage, storageType, cardSlot }
  rearCamera: CameraModule[]
  frontCamera: CameraModule[]
  vibration: { type, model?, size? }     // 马达:X轴/Z轴线性、转子;型号如 "AAC 0809"
  speakers: {
    count, stereo, units: { model?, size?, power? }[],
    dolbyAtmos, hiRes, loudnessDba?,
    headphoneJack
  }
  connectivity: { cellular, wifi, bluetooth, nfc, gps, usb, ir, uwb }
  battery: { capacity, type, wired, wireless, reverse, chargingProtocol }
  sensors: {
    fingerprint, fingerprintType, fingerprintPosition,
    gyro, barometer, colorSensor, flickerSensor, sar, ...
  }
  software: { launchVersion, currentVersion, updatePolicy }
  extra: Record<string, string>
}

CameraModule {
  position: 'wide' | 'ultrawide' | 'tele' | 'periscope' | 'macro' | 'depth' | 'mono' | 'front'
  sensorModel?          // "Sony IMX890"
  resolution, aperture, focalLength, sensorSize, pixelSize,
  lensElements,         // "7P"
  ois, eis,
  zoom?,                // "3x 光学 / 30x 数码"
  autofocusType?,       // "双像素 PDAF / 激光对焦"
  video: { max, modes[], stabilization }   // max: "8K@24fps"
  flash?
  extra
}

关键点:多摄必须逐颗建模,不能在 camera 里塞一个字符串数组。每颗摄像头独立一条记录,才能做出"主摄 IMX890 + 长焦 OV64B + 超广角 JN1"这种可检索、可对比的结构。

其他模板

  • 笔记本:display / cpu / gpu / memory / storage / keyboard / touchpad / ports / battery / thermal / speakers / webcam / wifi / weight / build
  • 台式机:cpu / gpu / motherboard / memory / storage / psu / case / cooling / ports
  • 显卡:arch / shaders / rtCores / tensorCores / memory(类型·容量·位宽·带宽) / bus / tdp / powerConnectors / outputs / pcie / dimensions / cooling
  • 外设(按 subCategory 再分套模板):显示器 panel/size/resolution/refreshRate/responseTime/brightness/contrast/colorGamut/hdr/ports/stand;键盘 layout/switch/actuation/travel/keycap/connection/battery;鼠标 sensor/dpi/reportRate/buttons/weight/connection;耳机 driver/impedance/frequencyResponse/anc/battery/codecs;存储 capacity/interface/seqRead/seqWrite/tbw/nand。

5.4 对比逻辑

  1. 校验同 category(外设再校验同 subCategory),2–4 台。
  2. 取各设备 specs 的扁平化路径并集,按模板定义的字段顺序排序(模板里就是渲染顺序)。
  3. 值比较前做归一化:拆成 { num, unit, raw },数值类字段(电池容量、屏幕亮度、重量、跑分)可用于排序与条形可视化。
  4. 不同则高亮;缺失显示 — 并置灰。
  5. 支持"只看差异"过滤与分组折叠。

6. 编辑验证("简单验证")

不做用户系统,只做单密钥:

  1. 环境变量 ADMIN_PASSWORD(哈希后存,不存明文)。
  2. POST /api/auth/login → 校验 → 签发 HttpOnly + SameSite=Lax + Secure cookie,内含签名 token(jose,有效期 7 天)。
  3. 中间件保护 /admin/* 与所有写接口。
  4. POST 接口校验 Origin,防 CSRF;登录接口做 IP 级限速(3 次/分钟)。
  5. 可选:TOTP 二次验证(otpauth),10 行代码,愿意的话加上更稳。

关键原则:读接口全部公开、无鉴权、可被 CDN 缓存;只有写接口和 AI 接口需要 token。AI 接口也要鉴权,否则会被人刷爆额度。


7. AI 能力设计

✅ 已采纳:OpenAI 兼容协议 + 独立搜索 API(Tavily/Exa)。

7.1 三类能力,按优先级

  1. 参数补全(P0):输入 品牌 + 型号,返回该分类的完整 specs JSON,每个字段带置信度与来源。
  2. 纠错/查缺(P1):指向已有设备,AI 对比公开资料指出错误字段与缺失字段。
  3. 文案生成(P2):生成客观简介与规格要点摘要(只写客观卖点,不写个人体验)。
  4. (可选)自然语言查询(P3):"哪些手机支持 144Hz 且重量低于 190g" → 转结构化筛选条件。

7.2 工程约束(很重要)

  • 绝不静默入库:AI 返回 → zod 校验 → 按置信度分级预填 → 人工核对 → 保存。AI 输出永远先落"草稿态"。
  • 必须联网:硬件参数迭代快,纯模型记忆幻觉严重。需要给模型接搜索工具(Tavily / Exa / Brave Search / 模型自带 web search)。
  • 字段级来源:每批 AI 结果附带 URL;写入 meta[],详情页用"已核实 / 待核实"徽章区分。
  • 缓存:以 category+brand+model 为 key 存到 ai_cache,避免重复付费。
  • 供应商可换:统一走 OpenAI 兼容协议(baseURL + apiKey + model 三个环境变量),可切 OpenAI / DeepSeek / 通义 / Kimi / 本地 Ollama。
  • 结构化输出:优先用 JSON Schema 模式(response_format: json_schema),失败则退回"JSON + zod 修复一轮"。
  • 成本:单次补全预计 1–3k tokens 输入;加缓存后日常开销可忽略。

7.3 置信度分级(核心机制)

AI 必须为每个字段输出置信度,前端据此决定默认行为:

级别 判定依据 前台行为 保存行为
high 官方规格页原文,或 ≥2 个独立来源一致 自动填入,绿色徽章 可直接保存
medium 单一非官方来源(评测、数据库站),或由多个字段推导 预填,黄色徽章 + "待核对" 可保存,但记录为未核实
low 模型推测、无出处、字段冲突 预填但标红,折叠进"待确认"区 阻塞保存,必须逐项确认或清空
无 未找到 留空 —

交互要求:

  • 每个字段右侧一个小徽章,hover 显示来源链接与抓取时间。
  • 顶部固定条显示"共 N 项待核对",点击跳到首个 low 项。
  • 批量操作:"全部接受 high"、"清空全部 low"。
  • 保存后 verified 按用户是否手动确认置位;详情页据此显示数据可信度。

7.4 接口草案

POST /api/ai/lookup   { category, brand, model }
  -> { fields: { path, value, confidence, sourceUrl? }[], sources: Url[], cached: boolean }

POST /api/ai/audit    { deviceId }
  -> { issues: { path, expected, current, confidence, sourceUrl? }[] }

POST /api/ai/summary  { deviceId }
  -> { summary, highlights: string[] }

fields 用扁平路径而非嵌套对象:前端可以直接按 path 合入、高亮、着色,不必维护两套结构树。


8. 动效与视觉

8.1 选型建议(✅ 已采纳克制型)

用途 方案 说明
页面切换 Astro View Transitions(transition:animate) 零依赖,自带淡入/滑动
列表渐入、卡片悬停 Motion(motion/react,在 island 内) useInView + stagger,体积约 30KB
数字滚动(跑分/容量) 自写 20 行 hook 不必引第三方
滚动叙事(首页 hero) GSAP + ScrollTrigger(可选,仅首页懒加载) 只在确实需要"一段横向滑动叙事"时才引
平滑滚动 Lenis(可选) 谨慎:会干扰可访问性,建议不开
骨架屏/加载 纯 CSS —

结论:主用 Astro View Transitions + Motion;GSAP 作为可选增强,不默认引入,避免三套动效库打架。

8.2 视觉方向

  • 深色为主、浅色可选;中性灰底 + 单一强调色(如青绿/琥珀)。
  • 大字号型号名 + 等宽字体的参数值(font-variant-numeric: tabular-nums),参数表对齐才好看。
  • 卡片:细边框 + 极轻内发光,悬停时 1px 描边渐亮,不做夸张投影。
  • 图片:设备正面照统一裁切比例(4:3 / 1:1),列表用同一角度,视觉更整齐。

9. 存储、部署与备份

9.1 图片存储驱动(本地 + 对象存储,双支持)

抽一层接口,默认本地,配置项一改就切对象存储:

interface StorageDriver {
  put(key: string, buf: Buffer, contentType: string): Promise<void>
  delete(key: string): Promise<void>
  publicUrl(key: string): string
}
  • local:写 data/uploads/,URL 走 /uploads/*,由 Astro 端点或静态服务返回。
  • s3:S3 兼容协议(AWS S3 / Cloudflare R2 / MinIO / Backblaze B2),配置 endpoint / bucket / region / accessKey / secretKey / publicBaseUrl。
  • 环境变量:STORAGE_DRIVER=local|s3,其余按驱动按需读取。

关键约束:数据库只存 key,绝不存绝对 URL。 这样换驱动、换域名时数据完全不用改(Device.cover 存 devices/xxx/cover.webp,渲染时由 driver 生成 URL)。

  • 上传即处理:sharp 生成 3 档(原图 / 1600w / 400w 缩略),转 WebP,原图保留。
  • 对象存储的 publicBaseUrl 可以是 CDN 域名。

9.2 备份与迁移的差异

驱动 备份方式 说明
local tar 打包 data/(db + uploads) 一份包即全量,最省心
s3 sqlite3 .backup + rclone sync 桶 两部分,脚本里分两条路径

9.3 实际部署方式(已上线)

服务器内存只有 1.6G,Docker 多阶段构建会触发 kcompactd0 长时间阻塞(load 40+,构建停在 “Rearranging server assets” 十几分钟不动),因此实际采用「宿主构建 + 容器挂载」:

/opt/lfspecs
├─ dist/          # 宿主 pnpm build 产物
├─ node_modules/  # 宿主 pnpm install(Linux,hoisted 结构)
├─ data/          # 持久化:app.db + uploads
└─ .env

容器只负责运行:node:24-slim + node dist/server/entry.mjs,挂载上面三个目录。部署脚本 scripts/deploy.sh 串起「拉代码 → install → build → compose 重启 → 健康检查」。

普通机器 / CI 仍可用仓库里的 Dockerfile 构建单镜像(docker compose build),不依赖挂载。

  • data/app.db(SQLite)、data/uploads/(图片)
  • 备份:pnpm backup → VACUUM INTO 快照 + 打包 uploads → backups/<时间戳>/
  • 迁移:新机器解包 data/ → 重新 pnpm install && pnpm build → 起容器
  • 导出:GET /api/export 输出版本化的全量 JSON(含 formatVersion),作为长期归档格式(M4 实现)
  • 定时:cron / 计划任务每日备份,保留 7 份轮转

使用 s3 驱动时,"图片随备份一起走"的前提消失,必须单独确认 rclone sync 是否成功——备份脚本要把两条路径的结果都打进日志。

9.4 必备的两条逃生通道

  • GET /api/export 全量 JSON(含 formatVersion),用于跨方案迁移或降级为静态站
  • POST /admin/import 导入并 zod 校验,拒绝脏数据

10. 分期

阶段 内容 产出
M0 脚手架、Tailwind、shadcn PoC(3 个组件)、zod schema、storage 驱动、repo 层 能跑的空站
M1 只读:手机列表/详情、芯片库、搜索筛选 + sitemap、JSON-LD 可看、可收录的站
M2 编辑:登录、表单(含字段级徽章)、图片上传、修订记录 可维护
M3 AI 分级补全(high 自动 / medium 标黄 / low 阻塞)+ 差异预览 录入效率
M4 对比页(差异高亮、只看差异、条形可视化)、导出导入、备份脚本 完整闭环
M5 动效打磨、OG 图、打印样式、部署上线 成品

11. 决策记录

# 决策 结论 影响
D1 部署与数据层 方案 A:VPS/NAS + Docker + Astro SSR + SQLite 需要一台常开机器;浏览器内可编辑;备份=tar
D2 AI 接入 OpenAI 兼容 + 独立搜索 API 多一个 SEARCH_API_KEY;参数可追溯来源
D3 组件库 先 PoC(Button/Card/Dialog)再定 M0 先验证 Astro + shadcn 手感,不急着全量采用
D4 动效 克制型:View Transitions + Motion,不引 GSAP/Lenis 首页不做滚动叙事,包体小
D5 站点定位 公开展示的规格库,收录任意型号,非个人资产 移除购入价/持有状态/时间线;加品牌页、JSON-LD、sitemap
D6 录入分级 high 自动填入 / medium 预填+标黄 / low 预填+阻塞保存 schema 需 FieldMeta;表单需置信度徽章与待核对汇总
D7 图片存储 本地 + S3 双驱动,DB 只存 key 存储抽象层;备份分两条路径
D8 芯片 独立实体,设备页引用并可展开、跳转、反查 多一张 chips 表与一套维护流程
D9 对比 同类别 2–4 台,差异高亮、只看差异、数值条形化 specs 需强模板与数值归一化
D10 参数颗粒度 细到传感器型号 / 马达型号 / 扬声器单元 手机模板需多摄逐颗建模,录入成本上升(由 AI 缓解)

11.1 已确认 / 待确认

已确认

  • 语言:仅中文,不做多语言;参数值保留英文原文(LPDDR5X-8533)。
  • 首批范围:只做手机 + 芯片(SoC),笔记本/台式/显卡/外设的模板与路由先留空壳后置。

待确认

  1. 站点名:见第 12 节的候选,选定后要查域名与商标。
  2. 数据来源声明:页脚是否常驻"数据由人工与 AI 辅助整理,仅供参考"?(建议加,公开站需要)。
  3. 是否允许被搜索引擎收录:公开站默认是,但如果初期数据还不完整,可以先 noindex 到 M5 再放开。

11.2 下一步(M0 开工清单)

  1. pnpm create astro(SSR)+ Tailwind v4 + @astrojs/node + @astrojs/react
  2. shadcn PoC:装 Button / Card / Dialog,写一页 demo 验证手感
  3. src/lib/schema/:先只做 phone 与 soc 两套 zod + FieldMeta
  4. src/lib/storage.ts:local 驱动先实现,s3 留接口
  5. src/lib/db.ts + migrations/001_init.sql(第 4.2 节表结构)
  6. src/lib/repo.ts 骨架 + 可跑通的 /devices 列表页(先读种子数据)
  7. Dockerfile / docker-compose,验证卷挂载与备份脚本

M0 完成标志:本地 docker compose up 能打开首页,/devices 与 /chips 各自从 SQLite 读出种子数据。

11.3 M0 实施记录(已完成)

  • 脚手架:Astro 7.4.4 + @astrojs/node 11(standalone)+ @astrojs/react 7 + Tailwind 4.3.3(@tailwindcss/vite)
  • 数据库:改用 Node 内置 node:sqlite(DatabaseSync),放弃 better-sqlite3,避免 Windows 原生编译与 Docker 交叉编译问题
  • 已落地:schema/(phone、soc、FieldMeta、Device/Chip 判别联合)、db.ts、repo.ts、storage.ts(local 已实现,s3 留接口)、migrations/001_init.sql、scripts/seed.mjs、scripts/backup.mjs
  • 页面:/、/devices、/devices/[slug]、/chips、/chips/[slug]、/poc、/uploads/[...path]
  • 验证:pnpm build 通过;生产产物 6 个路由全部 200、伪造 slug 返回 404;Dialog island 交互经浏览器验证可开可关;backup.mjs 用 VACUUM INTO 产出快照
  • 环境坑:本机 pnpm 全局 store D:\.pnpm-store 写权限不足导致 ERR_PNPM_EPERM,已用项目内 .npmrc(store-dir=.pnpm-store)规避
  • Docker:本地未安装;已在 ECS 上完成容器化运行验证,但构建方式改为「宿主构建 + 容器挂载」(见 9.3 / 11.5)

11.4 M1 实施记录(已完成并上线)

  • 搜索:brand / model / aliases_json / summary 的 LIKE 匹配,参数化 SQL,无 JS
  • 筛选与排序:品牌 chip 列表 + 最新发布 / 按型号 / 按品牌三种排序,全部是 GET 链接
  • 品牌页:/brands、/brands/[brand](品牌参数 URL 编码 + decodeURIComponent)
  • SEO:/sitemap.xml 动态端点(首页 / 列表 / 详情 / 芯片 / 品牌全覆盖)、robots.txt、详情页 Product JSON-LD、site 固定为 https://specs.atie.fun
  • 详情页补充:上市日期、生命周期、标签、字段级来源列表(按 confidence 着色,low 显示红色)
  • 验证:本地 pnpm build 通过;线上 10 个路由与筛选组合均为 200,sitemap 与 JSON-LD 内容正确

11.5 运行环境与踩坑记录(供换机后参考)

AliECS

  • SSH:atie.fun:22(root);公网 47.108.80.132;内网 172.29.109.56;Tailscale 100.64.0.4
  • Docker 24.0.7 / compose v2.21;内存 1.6G,磁盘 40G(约 62% 已用)
  • 宿主 3000 被 frps 占用,应用映射到 3010;80/443 由 openresty 接管(1panel)
  • 代码 /opt/lfspecs,数据 /opt/lfspecs/data,容器名 lfspecs
  • 宿主原本没有 Node,已装到 /opt/node(v24.22.2),deploy.sh 会自动加 PATH

已修改的系统配置

  • /etc/resolv.conf 改为 223.5.5.5 / 119.29.29.29(原阿里云内网 DNS 100.100.2.136/138 整体超时,导致 Docker 连镜像加速器都解析不了);原文件备份在 /etc/resolv.conf.bak
  • ufw allow 3010/tcp(阿里云安全组尚未放行 3010,公网直连不通;本机反代不受影响)
  • /etc/hosts 加了 47.108.80.132 gitea.atie.fun(Gitea 域名在 ECS 上无法解析,用于 clone)

坑位清单

  1. 本机 pnpm 全局 store 在 D:\.pnpm-store,无写权限 → 全部下载报 ERR_PNPM_EPERM;改用项目内 .npmrc 的 store-dir=.pnpm-store
  2. 沙箱模式下 pnpm 生成的 junction 被重定向到 …/trae cn/modulardata/… 虚拟路径,命令结束即失效,Node 报 Cannot find package;改用 node-linker=hoisted,且安装需在非沙箱下执行
  3. ECS 内存 1.6G 跑不动 Docker 多阶段构建(kcompactd0 阻塞);且绝不能并发跑两个 build,会直接把机器压到近乎无响应
  4. Gitea 在 AtieFN 的群晖套件里(/opt/1panel 与 /vol1/@appcenter/Gitea,端口 8418),未启用内置 SSH(START_SSH_SERVER 未开),gitea.atie.fun:22 实际落在 ECS 的 sshd → Deploy Key / SSH push 不可用
  5. 推送只能用 HTTPS 凭据;环境里的 GITEA_TOKEN 受安全策略限制无法被自动使用,代码同步需人工 git push,服务器侧只做 git fetch --depth 1 && git reset --hard origin/main

11.6 当前状态与后续待办

仓库

  • 8430e53 M0 脚手架(已推送)
  • 0c30c79 M1 只读增强(已推送)
  • 22aa0ef 部署方式改为宿主构建 + 挂载(本地已提交,待 git push)

线上

  • https://specs.atie.fun 待用户配置反代(目标 127.0.0.1:3010)
  • 可直接访问 http://<ECS>:3010(需安全组放行)或内网/Tailscale 地址

下一步(M2 起)

  1. M2 编辑后台:登录(ADMIN_PASSWORD + 签名 cookie)、设备/芯片表单、图片上传(storage.ts)、revisions 修订记录
  2. M3 AI 分级补全:/api/ai/lookup 返回扁平字段 + 置信度,表单按 high/medium/low 着色,low 阻塞保存
  3. M4 对比页(差异高亮、只看差异、数值条形化)、/api/export + /admin/import
  4. M5 动效打磨、OG 图、打印样式
  5. 换机续作时先执行 pnpm install(注意 .npmrc 的 hoisted 配置),再 pnpm db:seed 起本地数据

12. 站点命名(已定:LFSpecs)

已确认:对外站名用 LFSpecs。下表保留作为备选,仅当域名 lfspecs.* 不可用时再启用。

站名要满足三点:能表达"参数规格"、不绑定单一品类(手机/芯片/电脑都能装进去)、中文念着不别扭。

候选 域名建议 说明 风险
器谱 qipu.app / qipu.wiki "器物谱系"。一个字表,可扩展全部硬件;中文感强,不像厂商站 略抽象,需副标题解释
SpecDock specdock.dev dock = 停靠/汇总坞。英文顺口,SEO 词直白(spec 是核心搜索词) 英文站名在国内传播弱
机尺 jichi.app 手机 + 标尺双关,记忆点最强 只贴手机,扩展电脑时尴尬
规格集 specset.io 最中性直白,永不过时,搜索友好 平庸,没有品牌感
硬件谱 hwpu.app 通俗易懂,"硬件"覆盖广 商标与域名大概率被占

我的建议:器谱(qipu.app),理由:

  • "谱"天然承接"谱系/参数表",既像一个可查的表,又暗示"收录成体系",比"库""站"高级。
  • 不绑定品类——以后加显卡、外设,名字不用改;机尺 会卡住。
  • 两个音节,中文站点名里属于短的一档,好记也好念。

备选 SpecDock:如果你更希望技术上易被检索、且不介意英文名,它的 spec 前缀对 SEO 更友好。

两个都需要自己去查域名注册与商标情况,我只能给方向,无法保证可注册。选定后告诉我,我同步改 README 与文档标题。