bookworm-boot/quick-reference.txt

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

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

================================================================================
  一、首次安装 (目标机)
================================================================================

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

  注意: 安装 Node.js 后必须重开 PowerShell 窗口!
  注意: 如 npm 报 "执行策略" 错误, 先执行:
        Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

  # 1. 确保代理/VPN 已启动并连接

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

  # 3. 进入目录
  cd bookworm-boot

  # 4. 配置 git 记住密码 (避免重复输入)
  git config --global credential.helper store

  # 5. 运行安装
  #    PowerShell 7 (推荐):
  pwsh -ExecutionPolicy Bypass -File install.ps1
  #    PowerShell 5.1 (自带):
  powershell -ExecutionPolicy Bypass -File install.ps1

  # 脚本会自动:
  #   [0/7]   前置检查 (Claude Code / Node.js / Git)
  #   [0.5/7] 自动检测系统代理 (无需手动找端口)
  #   [1/7]   解密凭证 (输入主密码)
  #   [2/7]   克隆 Bookworm 配置 (97 Skills / 18 Agents / 28 Hooks)
  #   [3/7]~[6/7] 渲染配置 + 初始化目录
  #   [7/7]   启动 Claude Code

================================================================================
  二、后续启动 (已安装过)
================================================================================

  # 快速启动 (跳过 git clone, 仅解密凭证+启动, ~10秒)
  cd bookworm-boot
  pwsh -ExecutionPolicy Bypass -File install.ps1 -StartOnly

  # 同步最新配置后启动 (会 git pull 更新)
  cd bookworm-boot
  pwsh -ExecutionPolicy Bypass -File install.ps1

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

  # 基础清理 (清除环境变量, 保留配置供下次使用)
  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

================================================================================
  四、代理/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

================================================================================
  五、管理员操作 (你的电脑)
================================================================================

  ---- 5.1 部署 Gitea (仅首次) ----

  scp C:\Users\leesu\Desktop\bookworm-portable\deploy-gitea.sh root@8.138.11.105:/tmp/
  ssh root@8.138.11.105 "GITEA_ADMIN_PASS='[密码]' bash /tmp/deploy-gitea.sh"

  ---- 5.2 配置 HTTPS (仅首次) ----

  scp C:\Users\leesu\Desktop\bookworm-portable\setup-https.sh root@8.138.11.105:/tmp/
  ssh root@8.138.11.105 "bash /tmp/setup-https.sh"

  ---- 5.3 防火墙加固 (仅首次) ----

  scp C:\Users\leesu\Desktop\bookworm-portable\secure-firewall.sh root@8.138.11.105:/tmp/
  ssh root@8.138.11.105 "bash /tmp/secure-firewall.sh"

  ---- 5.4 推送 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

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

  cd C:\Users\leesu\AppData\Local\Temp\bookworm-boot
  cp C:\Users\leesu\Desktop\bookworm-portable\install.ps1 .
  cp C:\Users\leesu\Desktop\bookworm-portable\stop.ps1 .
  cp C:\Users\leesu\Desktop\bookworm-portable\guide.html .
  cp C:\Users\leesu\Desktop\bookworm-portable\secrets.enc .
  git add -A
  git commit -m "update boot scripts"
  git push https://bookworm:[密码]@code.letcareme.com/bookworm/bookworm-boot.git main

  ---- 5.6 重新加密凭证 (更换 API Key 后) ----

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

  # 加密完成后同步到 boot 仓库 (参照 5.5)

  ---- 5.7 解密验证 (检查凭证内容) ----

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

  ---- 5.8 生成完整性哈希 ----

  pwsh -ExecutionPolicy Bypass -File C:\Users\leesu\Desktop\bookworm-portable\generate-integrity.ps1

  # 生成后 commit 到 bookworm-config 仓库 (参照 5.4)

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

  # 登录 ECS
  ssh root@8.138.11.105

  # 查看 Gitea 状态
  ssh root@8.138.11.105 "systemctl status gitea"

  # 查看 Gitea 日志
  ssh root@8.138.11.105 "journalctl -u gitea -n 50"

  # 重启 Gitea
  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"

  # 手动解封 IP
  ssh root@8.138.11.105 "fail2ban-client set gitea unbanip 1.2.3.4"

  # 查看 Gitea 用户列表
  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"

  # 备份 Gitea 数据
  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 未启动, 或 Claude Code 未读到代理设置
  解决: 1. 确认代理软件已启动并连接
        2. 脚本会自动检测, 如失败则手动设置:
           $env:HTTPS_PROXY = "http://127.0.0.1:端口"
        3. 查找端口:
           [System.Net.WebRequest]::DefaultWebProxy.GetProxy("https://api.anthropic.com")

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

  问题: "openssl 未找到"
  解决: 确认 Git for Windows 已安装
        脚本自动搜索 C:\Program Files\Git 和 D:\Git 下的 openssl

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

  问题: "?.Source" 语法错误
  原因: 使用了 PowerShell 5.1, 不支持 ?. 语法
  解决: 用 pwsh (PowerShell 7) 代替 powershell (5.1)
        或更新到最新版 install.ps1 (已修复 PS5.1 兼容)

  问题: 中文乱码 / "<#" 错误
  原因: ps1 文件缺少 UTF-8 BOM
  解决: 用 pwsh (PowerShell 7) 或重新 git pull 获取最新文件

  问题: 克隆失败 / 认证失败
  解决: 1. 先配置 git 记住密码: git config --global credential.helper store
        2. 手动测试: git clone https://code.letcareme.com/bookworm/bookworm-config.git test
        3. 浏览器打开 https://code.letcareme.com 确认可达
        4. 如开了 2FA 需使用 Access Token 替代密码

  问题: 解密失败 / 主密码错误
  解决: 确认主密码正确 (区分大小写, 至少12位)
        如忘记密码需管理员重新 encrypt-secrets.ps1

  问题: Claude Code 启动无 Bookworm 横幅
  解决: 检查 ~/.claude/CLAUDE.md 是否存在
        重新运行 install.ps1 (不加 -StartOnly) 同步

  问题: git push 认证失败
  解决: URL 格式 https://bookworm:密码@code.letcareme.com/bookworm/仓库.git

  问题: 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 证书, 自动续期)
  凭证存储:    仅进程级环境变量, 不写磁盘, 不写注册表
  密码传递:    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
  代理检测:    自动检测系统代理, 支持 Clash/V2Ray/快柠檬等

================================================================================
  九、文件清单
================================================================================

  bookworm-portable\
  ├── deploy-gitea.sh              Gitea 部署脚本 (ECS)
  ├── setup-https.sh               HTTPS 配置脚本 (ECS)
  ├── secure-firewall.sh           防火墙加固脚本 (ECS)
  ├── prepare-repo.ps1             仓库初始化+推送 (本机)
  ├── generate-integrity.ps1       完整性哈希生成 (本机)
  ├── encrypt-secrets.ps1          凭证加密/解密 (本机)
  ├── settings.template.json       settings.json 模板
  ├── settings.local.template.json settings.local.json 模板
  ├── install.ps1                  安装/启动 (目标机) [含代理自动检测]
  ├── stop.ps1                     清理/恢复 (目标机)
  ├── guide.html                   HTML 保姆式教程
  ├── quick-reference.txt          本文档
  └── README.txt                   简要说明

  Gitea 仓库:
  ├── bookworm-config              Skills/Agents/Hooks/Scripts (514 文件, 14MB)
  └── bookworm-boot                install.ps1 + stop.ps1 + secrets.enc + guide.html

================================================================================
  Bookworm Portable v1.2 | 2026-04-01 | code.letcareme.com
================================================================================