bookworm-boot/quick-reference.txt

================================================================================
  Bookworm Portable v1.4 — 快速参考手册
  所有命令可直接复制粘贴执行
================================================================================

  Gitea 地址:  https://code.letcareme.com
  管理员账号:  [由管理员提供]
  管理员密码:  [由管理员提供]
  中转站地址:  [由管理员提供]
  ECS 服务器:  [由管理员提供]

================================================================================
  一、首次安装 — 最简方式 (推荐)
================================================================================

  前置要求:
    [必须] Node.js 18+    https://nodejs.org 下载 LTS
    [必须] Git            https://git-scm.com 下载安装
    [必须] 代理/VPN       Clash / V2Ray / 快柠檬 / 任意翻墙工具
                          (Claude Code 启动时检查 api.anthropic.com, 国内必须)

  方法 A: 一键安装器 (最简单)
  ─────────────────────────────
  1. 获取 Bookworm-Setup.bat (管理员发给你, 或从 Bookworm Web 下载页获取)
  2. 双击运行
  3. 按提示输入 Gitea 密码 + 主密码
  4. 完成! 桌面自动出现 Bookworm 快捷方式

  方法 B: 手动安装
  ─────────────────────────────
  # 1. 确保代理/VPN 已启动

  # 2. 安装 Claude Code (如未装)
  npm i -g @anthropic-ai/claude-code

  # 3. 克隆引导仓库
  git clone https://code.letcareme.com/bookworm/bookworm-boot.git

  # 4. 进入目录
  cd bookworm-boot

  # 5. 运行安装 (PowerShell 7 推荐, 5.1 也可)
  pwsh -ExecutionPolicy Bypass -File install.ps1

  # 脚本自动执行:
  #   [1/6] 前置检查 (缺依赖自动提示 winget 安装)
  #   [2/6] 代理自动检测 (无需手动找端口)
  #   [3/6] 解密凭证 (输入主密码, 最多3次重试, 可选本日免密)
  #   [4/6] 同步配置 (git clone 92 Skills / 18 Agents / 34 Hooks)
  #   [5/6] 渲染模板 + 初始化 + Bookworm 完整性验证 + MCP 检查
  #   [6/6] 启动 Claude Code

================================================================================
  二、日常使用
================================================================================

  方法 A: 双击 .bat (推荐)
  ─────────────────────────────
  bookworm-boot 文件夹 (或桌面快捷方式):
    启动Bookworm.bat        每天日常使用 (快速启动, 不更新)
    更新并启动Bookworm.bat  管理员通知有更新时使用

  启动时显示 "有 N 个新更新可用" → 双击 "更新并启动" 同步

  方法 B: 命令行
  ─────────────────────────────
  # 快速启动 (~10秒, 跳过 git clone)
  cd bookworm-boot
  pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly

  # 同步更新后启动
  cd bookworm-boot
  pwsh -ExecutionPolicy Bypass -File install.ps1

================================================================================
  三、密码说明
================================================================================

  本系统有两个密码, 不要搞混:

  Gitea 密码   克隆仓库时输入, 用于下载文件
  主密码       解密 API 凭证时输入, 用于启动 Claude Code

  密码输错:    最多 3 次重试, 3 次失败自动退出
  本日免密:    首次解密后脚本询问 "今日内免密启动? (y/n)"
               选 y 后当天再次启动无需输密码, 次日自动过期
  忘记密码:    联系管理员重新生成 secrets.enc

================================================================================
  四、使用完毕清理
================================================================================

  方法 A: 双击 卸载Bookworm.bat (最简单, 一键完整卸载)

  方法 B: 命令行
  ─────────────────────────────
  # 基础清理 (清除环境变量, 保留配置供下次使用)
  pwsh -ExecutionPolicy Bypass -File stop.ps1

  # 完整恢复 (删除 Bookworm, 恢复电脑原始 .claude 目录)
  pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore

  # 深度清理 (恢复 + 清除 PS 历史 + 清除 Git/凭证缓存)
  pwsh -ExecutionPolicy Bypass -File stop.ps1 -Restore -Deep

  [!] 在他人电脑/公用电脑上务必执行深度清理或双击 卸载Bookworm.bat

================================================================================
  五、代理/VPN 相关
================================================================================

  install.ps1 自动检测代理, 支持:
    - 系统代理 (Windows 设置里的代理)
    - Clash for Windows / Clash Verge
    - V2Ray / V2RayN
    - 快柠檬 / 任意 VPN
    - 其他设置了系统代理的工具

  如果自动检测失败, 手动指定:
  $env:HTTPS_PROXY = "http://127.0.0.1:端口号"
  $env:HTTP_PROXY = "http://127.0.0.1:端口号"
  pwsh -ExecutionPolicy Bypass -File install.ps1

  查找代理端口:
  [System.Net.WebRequest]::DefaultWebProxy.GetProxy("https://api.anthropic.com")
  # 输出中的 Port 就是代理端口

  常见代理端口:
    Clash:      7890
    V2RayN:     10808 / 10809
    快柠檬:     10792 (通过上述命令查询)
    SSR:        1080

================================================================================
  六、管理员操作
================================================================================

  ---- 6.1 推送 Bookworm 配置到 Gitea ----

  cd C:\Users\leesu\.claude
  git add -A
  git commit -m "update bookworm config"
  git push https://bookworm:[密码]@code.letcareme.com/bookworm/bookworm-config.git main

  ---- 6.2 更新 boot 仓库脚本 ----

  cd C:\Users\leesu\AppData\Local\Temp\bookworm-boot
  cp C:\Users\leesu\Documents\bookworm-portable\install.ps1 .
  cp C:\Users\leesu\Documents\bookworm-portable\stop.ps1 .
  cp C:\Users\leesu\Documents\bookworm-portable\guide.html .
  cp C:\Users\leesu\Documents\bookworm-portable\secrets.enc .
  cp "C:\Users\leesu\Documents\bookworm-portable\启动Bookworm.bat" .
  cp "C:\Users\leesu\Documents\bookworm-portable\更新并启动Bookworm.bat" .
  cp "C:\Users\leesu\Documents\bookworm-portable\卸载Bookworm.bat" .
  cp "C:\Users\leesu\Documents\bookworm-portable\Bookworm-Setup.bat" .
  git add -A
  git commit -m "update boot scripts"
  git push https://bookworm:[密码]@code.letcareme.com/bookworm/bookworm-boot.git main

  ---- 6.3 重新加密凭证 ----

  pwsh -ExecutionPolicy Bypass -File C:\Users\leesu\Documents\bookworm-portable\encrypt-secrets.ps1
  # 加密完成后同步到 boot 仓库 (参照 6.2)

  ---- 6.4 解密验证 ----

  pwsh -ExecutionPolicy Bypass -File C:\Users\leesu\Documents\bookworm-portable\encrypt-secrets.ps1 -Decrypt

  ---- 6.5 更新 Bookworm Web 下载页的安装器 ----

  scp C:\Users\leesu\Documents\bookworm-portable\Bookworm-Setup.bat root@8.138.11.105:/opt/bookworm-web/public/

================================================================================
  七、SSH 服务器管理
================================================================================

  # 登录 ECS
  ssh root@8.138.11.105

  # Gitea 状态/日志/重启
  ssh root@8.138.11.105 "systemctl status gitea"
  ssh root@8.138.11.105 "journalctl -u gitea -n 50"
  ssh root@8.138.11.105 "systemctl restart gitea"

  # Nginx 状态
  ssh root@8.138.11.105 "nginx -t && systemctl status nginx"

  # fail2ban 封禁/解封
  ssh root@8.138.11.105 "fail2ban-client status gitea"
  ssh root@8.138.11.105 "fail2ban-client set gitea unbanip 1.2.3.4"

  # 用户管理
  ssh root@8.138.11.105 "sudo -u git gitea admin user list --config /var/lib/gitea/custom/conf/app.ini"
  ssh root@8.138.11.105 "sudo -u git gitea admin user change-password --username bookworm --password NEW_PASSWORD --config /var/lib/gitea/custom/conf/app.ini"

  # 磁盘/备份
  ssh root@8.138.11.105 "du -sh /var/lib/gitea /home/git/gitea-repositories"
  ssh root@8.138.11.105 "sudo -u git gitea dump -c /var/lib/gitea/custom/conf/app.ini --tempdir /tmp"

================================================================================
  八、故障排查
================================================================================

  问题: "Unable to connect to Anthropic services" / "ECONNREFUSED"
  原因: 代理/VPN 未启动, 或 Node.js 未读到代理设置
  解决: 1. 确认代理已启动
        2. install.ps1 自动检测, 失败则手动:
           $env:HTTPS_PROXY = "http://127.0.0.1:端口"
        3. 查端口: [System.Net.WebRequest]::DefaultWebProxy.GetProxy(...)

  问题: "API Error: Invalid URL"
  原因: ANTHROPIC_BASE_URL 格式不对
  解决: 确保 secrets.enc 中值为 https://bww.letcareme.com/v1 (末尾含 /v1)
        不要在 settings.json env 段放 ANTHROPIC_BASE_URL

  问题: "openssl 未找到"
  解决: 确认 Git for Windows 已安装 (脚本搜索 C:\, D:\ 下的 Git 目录)

  问题: "执行策略" 错误
  解决: pwsh -ExecutionPolicy Bypass -File xxx.ps1
        或: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

  问题: "?.Source" 语法错误
  解决: 用 pwsh (PS 7) 或更新到最新 install.ps1 (已兼容 PS 5.1)

  问题: 中文乱码 / "<#" 错误
  解决: 用 pwsh (PS 7) 或 git pull 获取最新文件 (含 UTF-8 BOM)

  问题: 克隆失败 / 认证失败
  解决: 1. git config --global credential.helper store (install.ps1 已自动执行)
        2. 手动测试: git clone https://code.letcareme.com/bookworm/bookworm-config.git test
        3. 浏览器打开 https://code.letcareme.com 确认可达

  问题: 解密失败 / 密码错误
  解决: 区分大小写, 至少 12 位, 最多 3 次重试
        忘记密码需管理员重新 encrypt-secrets.ps1

  问题: Claude Code 启动无 Bookworm 横幅 / 显示 "原生模式"
  解决: 不加 -StartOnly 重新运行 install.ps1 同步最新配置

  问题: node -v / npm -v 无法识别
  解决: 安装 Node.js 后必须重开 PowerShell
        或: $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

  问题: npm 安装太慢
  解决: npm config set registry https://registry.npmmirror.com

================================================================================
  九、安全规格
================================================================================

  凭证加密:    AES-256-CBC + PBKDF2 (600,000 迭代, OWASP 2023)
  传输加密:    HTTPS TLS 1.2+ (Let's Encrypt 证书, 自动续期)
  凭证存储:    仅进程级环境变量, 不写磁盘, 不写注册表
  免密缓存:    Windows Credential Manager + DPAPI, 当日23:59过期
  密码传递:    openssl stdin 管道, 不暴露进程列表
  登录保护:    fail2ban (5 次失败/小时 -> 封禁 24 小时)
  二进制校验:  Gitea 下载 SHA-256 完整性校验
  Gitea 绑定:  127.0.0.1:3300 仅本地, 通过 Nginx 443 反代
  HSTS:        Strict-Transport-Security max-age=31536000
  注册控制:    DISABLE_REGISTRATION=true, INSTALL_LOCK=true
  代理检测:    3阶梯自动检测 (.NET DefaultWebProxy → 注册表 → 端口扫描)

================================================================================
  十、文件清单
================================================================================

  bookworm-portable\                     (本机管理员工具包)
  ├── Bookworm-Setup.bat                 一键安装器 (发给用户的唯一文件)
  ├── 启动Bookworm.bat                   日常双击启动
  ├── 更新并启动Bookworm.bat             同步后启动
  ├── 卸载Bookworm.bat                   一键完整卸载
  ├── install.ps1                        核心安装逻辑 (含代理检测/依赖安装/验证)
  ├── stop.ps1                           清理/恢复逻辑
  ├── encrypt-secrets.ps1                凭证加密/解密
  ├── generate-integrity.ps1             完整性哈希生成
  ├── prepare-repo.ps1                   仓库初始化+推送
  ├── deploy-gitea.sh                    Gitea 部署 (ECS)
  ├── setup-https.sh                     HTTPS 配置 (ECS)
  ├── secure-firewall.sh                 防火墙加固 (ECS)
  ├── settings.local.template.json       settings.local.json 模板
  ├── guide.html                         HTML 保姆式教程
  ├── quick-reference.txt                本文档
  ├── download.html                      独立下载页
  ├── download-panel.html                Bookworm Web 嵌入面板
  ├── lessons-learned.md                 踩坑经验 (10 项)
  └── README.txt                         简要说明

  Gitea 仓库:
  ├── bookworm-config                    Skills/Agents/Hooks/Scripts (514 文件, 14MB)
  └── bookworm-boot                      安装器+脚本+凭证+教程

  Bookworm Web 引流入口:
  └── /app → "下载" Tab                  内嵌下载页 + Bookworm-Setup.bat 直链

================================================================================
  Bookworm Portable v1.4 | 2026-04-02 | code.letcareme.com
================================================================================