MediaCrawler/mac-agent-os-main/archive_docs/matrix_docs/SETUP_ON_NEW_MACHINE.md

新机部署完整指南

目标: 在另一台 macOS (Apple Silicon) 机器上完整部署 Matrix 养号系统 预估时间: 30-60 分钟（不含首次登录各平台） 适用版本: v4.2+

---

目录

1. 环境准备
2. 同步代码
3. 安装依赖
4. 配置账号
5. 首次登录
6. 运行养号
7. 日常运维
8. 迁移账号（从旧机）
9. 故障排查

---

1. 环境准备

项目	要求	检查命令
macOS	Apple Silicon (M1/M2/M3)	uname -m → arm64
Python	3.10+	python3 --version
Git	已安装	git --version
Homebrew	可选，用于安装工具	brew --version
磁盘空间	5GB+	df -h ~

如果系统中没有 Python 3.10+，先安装：

# 通过 Homebrew
brew install [email protected]

# 或使用 pyenv
brew install pyenv
pyenv install 3.13.12

---

2. 同步代码

# 设定工作目录（建议与主机构一致）
export AGENT_SYNC="$HOME/workbuddy-agent-os/agent-sync"
export AGENT_LOCAL="$HOME/workbuddy-agent-os/agent-local"

# 克隆仓库（请先在本机配置好 Gitee SSH）
git clone [email protected]:babycalf/mac-agent-os.git "$AGENT_SYNC"

# 切换到 matrix 目录
cd "$AGENT_SYNC/05_tools/07_matrix"

网络说明：仓库托管在 Gitee（国内加速），如主仓库不可达请联系维护者获取同步方式。 本系统使用坚果云管理 agent-local 数据（非 Git），详见下文第 8 节。

---

3. 安装依赖

3.1 一键安装

cd "$AGENT_SYNC/05_tools/07_matrix"
bash install.sh

此脚本会：

• 创建 agent-local/tools/matrix/ 目录骨架
• 生成 local.yaml（本机路径配置文件）
• 安装 Python 依赖 (pip install -r requirements.txt)
• 安装 Playwright Chromium
• 检查账号配置

3.2 手动安装（如果 install.sh 失败）

# 建目录
mkdir -p "$AGENT_LOCAL/tools/matrix"/{config,data/cookies,profiles,logs,screenshots}
mkdir -p "$AGENT_LOCAL/tools/matrix/data/camoufox_pids"
mkdir -p "$AGENT_LOCAL/tools/matrix/backups/cookies"
mkdir -p "$AGENT_LOCAL/tools/matrix/accounts"/{douyin_01,douyin_02,douyin_camo01}/{content/{raw,edited,thumbnails},scripts/{drafts,posted},publish/{queue,published},backup/cookies}

# 安装 Python 包
pip install -r "$AGENT_SYNC/05_tools/07_matrix/requirements.txt"

# 安装 Playwright 浏览器
python -m patchright install chromium

# 初始化数据库
cd "$AGENT_SYNC/05_tools/07_matrix/scripts"
python init_db.py

# 生成 local.yaml
cat > "$AGENT_SYNC/05_tools/07_matrix/local.yaml" << EOF
matrix:
  local_data_root: $AGENT_LOCAL/tools/matrix
EOF

3.3 安装 Camoufox

Camoufox 是养号系统的核心引擎（Firefox 内核反检测浏览器）。

# 安装 Python 包
pip install camoufox

# 下载 Camoufox 浏览器二进制（约 200MB）
python -m camoufox fetch

# 验证安装
python -c "import camoufox; print(camoufox.__version__)"

安装完成后，Camoufox 可执行文件位于：

~/Library/Caches/camoufox/Camoufox.app/Contents/MacOS/camoufox

3.4 依赖清单

包	版本要求	用途
camoufox	≥0.4.11	Firefox 内核反检测浏览器
patchright	≥1.40	Playwright 浏览器自动化
browserforge	latest	浏览器指纹生成
PyYAML	≥5.0	YAML 配置解析
aiofiles	latest	异步文件操作
Pillow	latest	截图处理

完整清单见 requirements.txt。

---

4. 配置账号

4.1 复制配置模板

cp "$AGENT_SYNC/05_tools/07_matrix/config_template/accounts.yaml" \
   "$AGENT_LOCAL/tools/matrix/config/accounts.yaml"

4.2 编辑账号配置

编辑 $AGENT_LOCAL/tools/matrix/config/accounts.yaml，填入本机账号信息：

accounts:
  # ── 抖音账号 ──
  - id: douyin_01
    platform: douyin
    phone: "185xxxx8610"          # 改为本机手机号
    identity_dir: identities/douyin_01_camo   # 身份目录名
    window: [702, 783]            # 窗口尺寸
    window_position: [0, 0]       # 屏幕坐标（多账号防重叠）
    enabled: true

  - id: douyin_02
    platform: douyin
    phone: "185xxxx3366"
    identity_dir: identities/douyin_02_camo
    window: [702, 783]
    window_position: [400, 0]     # 紧贴 douyin_01 右侧
    enabled: true

  - id: douyin_camo01
    platform: douyin
    phone: "153xxxx8283"
    identity_dir: identities/douyin_camo01
    window: [702, 783]
    window_position: [750, 0]     # 再往右偏移
    enabled: true

  # ── 小红书账号（共享身份目录）──
  - id: xhs_01
    platform: xiaohongshu
    phone: "185xxxx8610"          # 与 douyin_01 同手机号
    identity_dir: identities/douyin_01_camo  # ← 共享！
    window: [702, 783]
    window_position: [0, 800]     # 抖音下方
    enabled: true

  - id: xhs_02
    platform: xiaohongshu
    phone: "185xxxx3366"
    identity_dir: identities/douyin_02_camo  # ← 共享！
    window: [702, 783]
    window_position: [400, 800]
    enabled: true

  - id: xhs_03
    platform: xiaohongshu
    phone: "153xxxx8283"
    identity_dir: identities/douyin_camo01   # ← 共享！
    window: [702, 783]
    window_position: [750, 800]
    enabled: true

关键规则：

• identity_dir 决定浏览器指纹和登录态目录，同手机号不同平台应共用同一目录
• 共享 identity_dir 时，Cookie 保护由 cookie_manager.py 自动处理
• window_position 控制浏览器启动位置，避免窗口重叠

4.3 配置代理（可选）

如需为每个账号配置独立静态代理 IP，在账号配置中添加 proxy 字段：

  - id: douyin_01
    ...
    proxy: socks5://127.0.0.1:1080   # 可选

详细 IP 方案见 IP_SWITCH_GUIDE.md。

---

5. 首次登录

新机首次需要手动登录各平台账号，建立登录态。

5.1 单账号首次登录

cd "$AGENT_SYNC/05_tools/07_matrix/scripts"
python matrix.py account login douyin_01

此命令会：

1. 启动 Camoufox 并加载对应 identity
2. 打开抖音登录页面
3. 等待你手动扫码/短信登录
4. 登录完成后回车确认 → session cookie 自动保存

5.2 验证登录状态

python matrix.py account status douyin_01
# → 应显示 "已登录" 及 cookie session id

python matrix.py account status   # 查看所有账号

5.3 批量首次登录的小技巧

由于抖音和小红书共享 identity_dir，先登录抖音，小红书自动复用：

douyin_01 登录完成 → xhs_01 自动可用
douyin_02 登录完成 → xhs_02 自动可用
douyin_camo01 登录完成 → xhs_03 自动可用

所以只需要登录 3 次，覆盖 6 个账号。

---

6. 运行养号

6.1 快速测试

先单账号跑一圈，验证系统是否正常：

cd "$AGENT_SYNC/05_tools/07_matrix/scripts"

# 抖音单账号 2 轮（约 2-3 分钟）
python matrix.py nurture run -a douyin_01 -r 2

观察日志 /tmp/matrix_nurture_douyin_01.log，确认：

• Camoufox 浏览器启动成功
• 进入播放页正常
• 能滑视频
• 评论正常

6.2 多账号并发

# 抖音三账号并行 10 轮（约 15-20 分钟）
python matrix.py nurture run \
    -a douyin_01 -a douyin_02 -a douyin_camo01 \
    -r 10 --no-daemon

各账号日志 /tmp/matrix_nurture_{account}.log，实时查看：

tail -f /tmp/matrix_nurture_douyin_01.log

6.3 全自动主控脚本

# 抖音 → 小红书 完整流程
bash "$AGENT_SYNC/05_tools/07_matrix/scripts/nurture_master.sh"

主控脚本执行顺序：

1. Phase 0: 全量 Cookie 备份
2. Phase 1: 抖音 3 账号并行（--no-daemon，完成后关浏览器）
3. 休息 30 秒
4. Phase 2: 小红书 3 账号并行

日志输出：

• 阶段日志：/tmp/nurture_master/{douyin|xhs}_phase.log
• 各账号日志：/tmp/matrix_nurture_{account}.log

6.4 定时任务

使用 cron 或 macOS launchd 设置每日自动运行：

# crontab 示例（每天 10:00）
0 10 * * * /bin/bash /path/to/nurture_master.sh >> /tmp/nurture_daily.log 2>&1

---

7. 日常运维

7.1 清理残留锁文件

养号异常退出后，Camoufox 可能留下 .parentlock 文件，导致下次启动失败：

# 清理所有 identity 的锁文件
find "$AGENT_LOCAL/tools/matrix/identities" -name ".parentlock" -delete

建议在每次运行前执行此命令。

7.2 Cookie 备份与恢复

备份位置：$AGENT_LOCAL/tools/matrix/backups/cookies/

# 手动备份所有账号
python -c "
from matrix_modules.utils.cookie_manager import backup_all_identities
backup_all_identities(platform='manual', label='manual_backup')
"

7.3 查看执行报告

# 查看各账号最后一轮结果
for acct in douyin_01 douyin_02 douyin_camo01 xhs_01 xhs_02 xhs_03; do
  log="/tmp/matrix_nurture_${acct}.log"
  [ -f "$log" ] && echo "=== $acct ===" && grep "轮数:\|耗时:\|完成" "$log" | tail -2
done

7.4 更新代码

cd "$AGENT_SYNC"
git pull origin main

如果本地有未提交的修改：

git stash        # 暂存本地修改
git pull origin main
git stash pop    # 恢复本地修改

---

8. 迁移账号（从旧机）

如果需要将旧机器的已登录账号迁移到新机，有两种方式：

方式 A：全量身份目录迁移（推荐）

将旧机器 agent-local/tools/matrix/identities/ 下的目录打包：

# 旧机器上打包
tar czf identities_backup.tar.gz \
  -C ~/workbuddy-agent-os/agent-local/tools/matrix/identities \
  douyin_01_camo douyin_02_camo douyin_camo01

# 通过 U 盘/网络传至新机

# 新机器上解压
tar xzf identities_backup.tar.gz \
  -C ~/workbuddy-agent-os/agent-local/tools/matrix/identities/

迁移后可能需要重新登录（取决于 Cookie 时效性）。

方式 B：坚果云同步

如果旧机和新机都安装了坚果云，可以通过坚果云同步 agent-local 目录（注意排除大文件）：

坚果云同步路径: ~/NutstoreCloudBridge/matrix-identities/
排除: *.parentlock, *.log

---

9. 故障排查

9.1 Camoufox 启动失败

错误: TargetClosedError / EPIPE

原因：.parentlock 残留 或 Playwright driver 崩溃

解决：

# 清理锁文件
find "$AGENT_LOCAL/tools/matrix/identities" -name ".parentlock" -delete

# 清理 Playwright 残留进程
pkill -f "playwright"
pkill -f "camoufox"

9.2 小红书页面刷挂起

日志卡在: "🔄 刷新瀑布流页面..."

原因：XHS Page.reload 超时后协程未正常退出

解决：

# kill 当前进程
# 清理锁文件后重跑
find ... -name ".parentlock" -delete
python matrix.py nurture run -a xhs_02 -r 10

9.3 小红书 QR 码拦截墙

日志显示: "🚫 QR码拦截墙（回退重试 1/3）"

原因：账号被平台标记为非常用登录环境

解决：系统会自动 3 轮回退重试，多数情况可自行恢复。 如果持续触发，尝试：

1. 手动打开浏览器在该账号下正常浏览几分钟
2. 清除 cookies 后重新登录
3. 检查代理 IP 是否与该账号常用地一致

9.4 抖音评论触发短信验证码

日志显示: "⏱️ SMS 验证码超时"

原因：抖音检测到异常评论行为，要求短信验证

解决：

• 暂时跳过评论（系统已自动跳过）
• 增加养号间隔（调大 behavior.base_delay）
• 换个评论内容

9.5 评论聚焦失败

日志显示: "⚠️ 所有聚焦方式均失败 (state=panel_open)"

原因：坐标偏移 / DOM 变化 / Draft.js 版本更新

解决：系统已自动跳过评论，不影响浏览养号。可尝试重新校准 （运行 python calibrate_input.py 重新采集坐标）。

9.6 日志太长，不清除旧记录

养号系统使用追加写日志，多次运行日志会混合。如需清理：

# 清理所有养号日志
rm -f /tmp/matrix_nurture_*.log
rm -f /tmp/nurture_master/*.log

---

附录：养号行为参数

行为参数可在 identities/{name}/config.yaml 中覆盖默认值：

behavior:
  base_delay: 1.5              # 操作间隔(秒)
  delay_variance: 0.8          # 随机波动范围
  attention:
    distraction_chance: 0.05   # "分心"概率
    watch_duration: [4, 12]    # 观看时长(秒)
  round_break:
    min_break: 5               # 轮间最短休息(秒)
    max_break: 20              # 轮间最长休息(秒)

---

附录：关键文件索引

文件	说明
scripts/matrix.py	统一 CLI，所有操作的入口
scripts/nurture_master.sh	养号主控脚本
scripts/matrix_modules/runner.py	养号循环引擎
scripts/matrix_modules/behavior.py	行为参数化
scripts/matrix_modules/utils/cookie_manager.py	Cookie 安全
scripts/ops/douyin/browse.py	抖音浏览操作
scripts/ops/douyin/interact.py	抖音交互操作
scripts/douyin_ops.py	抖音原子操作（旧方案）
blueprints/douyin_browse_v2.yaml	抖音日常浏览蓝图
local.yaml	本机路径配置（每机独立）