# 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) ```sql 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 部署产物 ```yaml # 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` 收纳长尾参数。不再"弱 schema"——对比页依赖字段一致性。 - **字段级元数据**:每个值都能携带 `confidence / sourceUrl / verified / capturedAt`。这是 AI 分级录入的基础,也是公开展示"数据可信度"的依据。 - **产品导向**:只记录产品客观参数,不含购入价、个人评价、持有状态。 ### 5.2 实体 **Device(设备)** — 手机、平板、笔记本、台式机、掌机、外设统一入口,用 `category` 区分。 ```ts 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` 引用,支持反查"搭载该芯片的机型"。 ```ts 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 分级机制配套。 ```ts 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 手机规格模板(细化版) ```ts 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 } 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 图片存储驱动(本地 + 对象存储,双支持) 抽一层接口,默认本地,配置项一改就切对象存储: ```ts interface StorageDriver { put(key: string, buf: Buffer, contentType: string): Promise delete(key: string): Promise 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://: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 与文档标题。