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）

本节记录当前已部署的真实配置（供 AI 直接执行/更新使用）。

✅ 当前部署清单（必须保持一致）

部署目录

• 代码根目录：/home/xxl/Code/bookmark

域名与端口

• 前端 Web：http://mark.cloud-xl.top:9527
• 后端 API 代理：http://mark.cloud-xl.top:9526（转发到后端 3001）

后端运行方式

• systemd：browser-bookmark-server.service
• 后端监听端口：SERVER_PORT=3001（由 .env 提供）

前端运行方式

• Docker 容器：nginx
• 端口映射：9527 -> 80
• Web 根目录（容器内）：/usr/share/nginx/html
• 挂载来源：/home/xxl/Code/bookmark/apps/web/dist

API 代理方式

• Docker 容器：nginx-api
• 端口映射：9526 -> 80
• 代理目标：http://host.docker.internal:3001
• 配置文件：/home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.api.conf

扩展包

• 构建输出：/home/xxl/Code/bookmark/apps/extension/dist
• 打包文件：/home/xxl/Code/bookmark/apps/extension/extension-dist.zip
• 下载地址：http://mark.cloud-xl.top:9527/extension-dist.zip

防火墙放行（iptables）

• 已放行：9526、9527

1) 初次部署/重建（在服务器执行）

路径：/home/xxl/Code/bookmark

npm install
npm run build

说明：

• Web 构建产物：apps/web/dist/
• 扩展构建产物：apps/extension/dist/
• 后端运行仍是 apps/server/src/

2) 数据库初始化

cd /home/xxl/Code/bookmark
npm -w apps/server run db:migrate

3) systemd 启动后端（并开机自启）

sudo cp /home/xxl/Code/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

4) 前端 Docker Nginx（9527）

sudo docker stop nginx || true
sudo docker rm nginx || true
sudo docker run -d --name nginx -p 9527:80 \
  -v /home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.conf:/etc/nginx/conf.d/default.conf:ro \
  -v /home/xxl/Code/bookmark/apps/web/dist:/usr/share/nginx/html:ro \
  nginx:latest

5) API 代理 Docker Nginx（9526）

sudo docker stop nginx-api || true
sudo docker rm nginx-api || true
sudo docker run -d --name nginx-api -p 9526:80 \
  --add-host=host.docker.internal:host-gateway \
  -v /home/xxl/Code/bookmark/deploy/nginx/mark.cloud-xl.top.api.conf:/etc/nginx/conf.d/default.conf:ro \
  nginx:latest

6) 防火墙放行

sudo iptables -I UG_INPUT 1 -p tcp --dport 9527 -j ACCEPT
sudo iptables -I UG_INPUT 1 -p tcp --dport 9526 -j ACCEPT

7) 生成并发布扩展包

cd /home/xxl/Code/bookmark/apps/extension/dist
zip -r ../extension-dist.zip .
cp /home/xxl/Code/bookmark/apps/extension/extension-dist.zip /home/xxl/Code/bookmark/apps/web/dist/extension-dist.zip

8) 验证清单（服务器内）

curl -s http://127.0.0.1:9527 | head -n 5
curl -s http://127.0.0.1:9526/health
curl -I http://127.0.0.1:9527/extension-dist.zip

9) 更新流程（以后改代码时）

每次修改后都按以下顺序更新，保证线上一致。

1. 构建（服务器或本地）
   • npm install
   • npm run build
2. 更新 Web 访问后端端口
   • 修改 apps/web/.env.production 中的 VITE_SERVER_BASE_URL，保持为 http://mark.cloud-xl.top:9526
   • 重新执行 npm -w apps/web run build
3. 重启后端
   • sudo systemctl restart browser-bookmark-server
4. 更新扩展包
   • 重新执行「生成并发布扩展包」步骤
5. 若修改 Nginx 配置
   • 重新创建容器（见第 4/5 步）
6. 验证
   • 按第 8 步执行检查