diff --git a/quick-reference.txt b/quick-reference.txt new file mode 100644 index 0000000..589c232 --- /dev/null +++ b/quick-reference.txt @@ -0,0 +1,292 @@ + +================================================================================ + Bookworm Portable v1.2 — 快速参考手册 + 所有命令可直接复制粘贴执行 +================================================================================ + + Gitea 地址: https://code.letcareme.com + 管理员账号: bookworm + 管理员密码: [REDACTED_OLD_PASSWORD] + 中转站地址: https://bww.letcareme.com/v1 + ECS 服务器: 8.138.11.105 (Gitea 端口 3300, 仅本地) + +================================================================================ + 一、首次安装 (目标机) +================================================================================ + + 前置要求: + [必须] 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='[REDACTED_OLD_PASSWORD]' 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:[REDACTED_OLD_PASSWORD]@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:[REDACTED_OLD_PASSWORD]@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 +================================================================================