154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
# 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 步执行检查
|