Xu_BrowserBookmark/README.md

BrowserBookmark

内部私域书签管理：Web + 浏览器扩展（MV3）。

环境要求

• Node.js 22+
• 包管理器：npm
• Postgres（仅后端直连）
• OpenSpec（全局安装）：npm install -g @fission-ai/openspec@latest

开发

• 启动后端：npm run dev:server
• 启动 Web：npm run dev:web
• 启动扩展：npm run dev:extension
• 同时启动（server+web）：npm run dev

规范（Spec-first）

• 规范在 spec/openapi.yaml
• 校验：npm run spec:lint / npm run spec:validate

配置

• 复制 .env.example 为 .env 并填写数据库与密钥。

发布（NAS / SSH / x86 Linux）

以下步骤适用于你描述的环境：x86 Linux NAS + SSH 部署，已安装 Node.js 24 与 pm2。

0) 本地已执行的命令（在本机开发环境）

• 路径：仓库根目录
• 已执行：
  • npm install
  • npm run build

这会生成下列产物：

• Web 构建产物：apps/web/dist/
• 扩展构建产物：apps/extension/dist/
• 后端为 Node 直接运行源代码（apps/server/src/）

1) 服务器目录建议（NAS）

建议在 NAS 上建立如下目录结构（可按需调整）：

/opt/browser-bookmark/
├── server/            # 后端源码与依赖
├── web/               # Web 静态站点
└── extension/         # 扩展构建产物（用于打包/发布或本地加载）

2) 通过 SSH 上传文件

以下是需要上传的内容与目标路径：

1. 后端（运行源码）

   • 本地：apps/server/
   • 服务器：/opt/browser-bookmark/server/

2. Web 前端（静态产物）

   • 本地：apps/web/dist/
   • 服务器：/opt/browser-bookmark/web/

3. 扩展产物（打包或本地加载）

   • 本地：apps/extension/dist/
   • 服务器：/opt/browser-bookmark/extension/

4. 部署配置文件

   • 本地：deploy/
   • 服务器：/opt/browser-bookmark/deploy/

你可以使用 scp 或 rsync（示例命令需替换服务器地址与用户名）：

# 后端源码
rsync -avz ./apps/server/ user@YOUR_NAS:/opt/browser-bookmark/server/

# Web 构建产物
rsync -avz ./apps/web/dist/ user@YOUR_NAS:/opt/browser-bookmark/web/

# 扩展构建产物
rsync -avz ./apps/extension/dist/ user@YOUR_NAS:/opt/browser-bookmark/extension/

# 部署配置
rsync -avz ./deploy/ user@YOUR_NAS:/opt/browser-bookmark/deploy/

3) 服务器端安装依赖

登录到 NAS：

ssh user@YOUR_NAS

在服务器的后端目录安装依赖：

cd /opt/browser-bookmark/server
npm install --omit=dev

4) 配置环境变量

在服务器 server 目录准备 .env：

cd /opt/browser-bookmark/server
cp .env.example .env

根据你的数据库与密钥填写 .env。

5) 初始化数据库（首次部署必做）

cd /opt/browser-bookmark/server
npm run db:migrate

6) 使用 systemd 启动后端

本仓库已生成 systemd 服务文件：deploy/systemd/browser-bookmark-server.service。

将其复制到服务器并启用：

sudo cp /opt/browser-bookmark/deploy/systemd/browser-bookmark-server.service /etc/systemd/system/browser-bookmark-server.service
sudo systemctl daemon-reload
sudo systemctl enable browser-bookmark-server
sudo systemctl start browser-bookmark-server

查看服务状态：

sudo systemctl status browser-bookmark-server

7) 配置 Nginx（端口 6666）

本仓库已生成 Nginx 配置文件：deploy/nginx/mark.cloud-xl.top.conf。

将其复制到服务器并启用：

sudo cp /opt/browser-bookmark/deploy/nginx/mark.cloud-xl.top.conf /etc/nginx/conf.d/mark.cloud-xl.top.conf
sudo nginx -t
sudo systemctl reload nginx

该配置将 mark.cloud-xl.top:6666 指向 /opt/browser-bookmark/web/。

8) 扩展发布/加载

扩展产物位于服务器：/opt/browser-bookmark/extension/。

• 如需本地加载：将该目录下载到你的桌面浏览器，用“加载已解压扩展”指向该目录。
• 如需打包发布到商店：以该目录为基础打包（按平台要求）。

9) 验证与排查

• 后端日志：

  sudo journalctl -u browser-bookmark-server -f
  

• Web 是否可访问（浏览器访问你的域名/端口）。
• 扩展是否能正常登录与同步。

10) 版本更新流程（建议）

1. 本地执行：npm install 与 npm run build
2. 重新上传：apps/server/、apps/web/dist/、apps/extension/dist/
3. 服务器端：npm install --omit=dev（如依赖变更）
4. 重启服务：sudo systemctl restart browser-bookmark-server