lan-reader-chat/docs/macbook-deployment.md

MacBook 局域网部署流程

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

一、推荐部署目录

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

/Users/ops/lan-reader-chat

目录约定：

/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

建议先确认：

node -v
npm -v

三、首次部署

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

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

2. 安装依赖：

   npm install
   

3. 创建存储目录：

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

4. 首次构建：

   npm run build
   

5. 本机验证：

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

浏览器访问：

http://localhost:3000

局域网其他设备访问：

http://MacBook局域网IP:3000

四、OpenClaw agent 状态接入

网站默认读取：

storage/agents/openclaw-agents.json

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

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

推荐方式：

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

示例：

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

五、开机自启

建议使用 launchd。

你可以参考：

• com.lan-reader-chat.web.plist
• com.lan-reader-chat.agentfeed.plist

安装方式示例：

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. 做回归验证

示例：

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