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）

本节记录**当前已部署的真实配置**（供 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`**

```bash
npm install
npm run build
```

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

### 2) 数据库初始化

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

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

```bash
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）

```bash
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）

```bash
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) 防火墙放行

```bash
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) 生成并发布扩展包

```bash
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) 验证清单（服务器内）

```bash
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 步执行检查