From 787544eec1e3f03ccd873511e5f4f99f1d1f8328 Mon Sep 17 00:00:00 2001 From: zhongluofeng Date: Fri, 30 Oct 2026 17:45:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=9B=9E=E5=A1=AB=EF=BC=9AM1?= =?UTF-8?q?=20=E5=AE=9E=E6=96=BD=E8=AE=B0=E5=BD=95=E3=80=81=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E7=8E=AF=E5=A2=83=E4=B8=8E=E8=B8=A9=E5=9D=91=E3=80=81?= =?UTF-8?q?=E5=90=8E=E7=BB=AD=E5=BE=85=E5=8A=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DESIGN.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 7 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 2c98be1..48e641e 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -519,17 +519,26 @@ interface StorageDriver { | local | `tar` 打包 `data/`(db + uploads) | 一份包即全量,最省心 | | s3 | `sqlite3 .backup` + `rclone sync` 桶 | 两部分,脚本里分两条路径 | -### 9.3 方案 A 落地细节 +### 9.3 实际部署方式(已上线) + +服务器内存只有 1.6G,Docker 多阶段构建会触发 `kcompactd0` 长时间阻塞(load 40+,构建停在 “Rearranging server assets” 十几分钟不动),因此实际采用「宿主构建 + 容器挂载」: ``` -docker-compose.yml - volumes: ./data:/app/data +/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` → `sqlite3 .backup` + tar → `backups/2026-10-30.tar.gz` -- **迁移**:新机器解包 → `docker compose up -d` → 完成 -- **导出**:`GET /api/export` 输出版本化的全量 JSON(含 `formatVersion`),作为长期归档格式 +- **备份**:`pnpm backup` → `VACUUM INTO` 快照 + 打包 uploads → `backups/<时间戳>/` +- **迁移**:新机器解包 `data/` → 重新 `pnpm install && pnpm build` → 起容器 +- **导出**:`GET /api/export` 输出版本化的全量 JSON(含 `formatVersion`),作为长期归档格式(M4 实现) - **定时**:cron / 计划任务每日备份,保留 7 份轮转 > 使用 s3 驱动时,"图片随备份一起走"的前提消失,必须单独确认 `rclone sync` 是否成功——备份脚本要把两条路径的结果都打进日志。 @@ -600,7 +609,55 @@ M0 完成标志:**本地 `docker compose up` 能打开首页,`/devices` 与 - 页面:`/`、`/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,Dockerfile / docker-compose 未实际跑过,需在有 Docker 的环境确认 +- 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` 起本地数据 ---