# MacBook 局域网部署流程

本文档用于把当前网站部署到一台局域网内的 MacBook 上，供公司内部用户访问。

## 一、推荐部署目录

建议在 MacBook 上使用固定目录：

```text
/Users/ops/lan-reader-chat
```

目录约定：

```text
/Users/ops/lan-reader-chat
├─ app/
├─ components/
├─ data/
├─ docs/
├─ lib/
├─ scripts/
├─ storage/
│  ├─ agents/
│  ├─ chat-uploads/
│  └─ chat.sqlite
├─ .next/
├─ package.json
└─ next.config.ts
```

说明：

- `storage/chat.sqlite`：聊天记录数据库
- `storage/chat-uploads/`：图片和文件上传目录
- `storage/agents/openclaw-agents.json`：OpenClaw agent 状态文件

## 二、基础环境

MacBook 上建议准备：

1. `Node.js LTS`
2. `npm`
3. 一个专门的运行用户，例如 `ops`

建议先确认：

```bash
node -v
npm -v
```

## 三、首次部署

1. 把项目放到目标目录：

```bash
cd /Users/ops
git clone <your-repo> lan-reader-chat
cd /Users/ops/lan-reader-chat
```

2. 安装依赖：

```bash
npm install
```

3. 创建存储目录：

```bash
mkdir -p storage/agents
mkdir -p storage/chat-uploads
```

4. 首次构建：

```bash
npm run build
```

5. 本机验证：

```bash
npm run start -- --hostname 0.0.0.0 --port 3000
```

浏览器访问：

```text
http://localhost:3000
```

局域网其他设备访问：

```text
http://MacBook局域网IP:3000
```

## 四、OpenClaw agent 状态接入

网站默认读取：

```text
storage/agents/openclaw-agents.json
```

如果 OpenClaw 的输出文件不在这个路径，可以通过环境变量指定：

```bash
OPENCLAW_AGENT_FEED_PATH=/some/path/openclaw-agents.json
```

推荐方式：

- OpenClaw 或 ops agent 定时生成 JSON
- 用项目内的同步脚本落到网站目录

示例：

```bash
node scripts/sync-openclaw-agent-feed.mjs /tmp/openclaw-agents.json
```

## 五、开机自启

建议使用 `launchd`。

你可以参考：

- [com.lan-reader-chat.web.plist](C:\Users\LA\Documents\New%20project\deploy\macos\com.lan-reader-chat.web.plist)
- [com.lan-reader-chat.agentfeed.plist](C:\Users\LA\Documents\New%20project\deploy\macos\com.lan-reader-chat.agentfeed.plist)

安装方式示例：

```bash
mkdir -p ~/Library/LaunchAgents
cp deploy/macos/com.lan-reader-chat.web.plist ~/Library/LaunchAgents/
cp deploy/macos/com.lan-reader-chat.agentfeed.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lan-reader-chat.web.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lan-reader-chat.agentfeed.plist
launchctl enable gui/$(id -u)/com.lan-reader-chat.web
launchctl enable gui/$(id -u)/com.lan-reader-chat.agentfeed
```

## 六、更新流程

每次更新建议按这个顺序：

1. 备份数据
2. 拉代码
3. 安装依赖
4. 重新构建
5. 重启服务
6. 做回归验证

示例：

```bash
cd /Users/ops/lan-reader-chat
cp storage/chat.sqlite storage/chat.sqlite.bak
git pull
npm install
npm run build
launchctl kickstart -k gui/$(id -u)/com.lan-reader-chat.web
```

## 七、部署后必须验证

至少检查：

1. 首页是否可访问
2. 聊天室是否可发文字
3. 图片 / 文件是否可上传
4. 聊天记录在服务重启后是否保留
5. `/agents` 是否能显示真实 OpenClaw 状态
6. 小说书架和阅读页是否正常打开

## 八、恢复与回滚

如果更新后异常：

1. 停止服务
2. 恢复 `chat.sqlite`
3. 恢复上一个版本代码
4. 重新 build
5. 重新启动

重点保护目录：

- `storage/chat.sqlite`
- `storage/chat-uploads/`
- `storage/agents/openclaw-agents.json`