DevDocs 维护者如何用 thor docs:upload 上传文档更新到 S3 并部署 Heroku【免费下载链接】devdocsAPI Documentation Browser项目地址: https://gitcode.com/GitHub_Trending/de/devdocs当 DevDocs 维护者更新了某份文档的 scraper 并本地重新生成后还需要完成两件事把文档文件与打包产物上传到 S3供 Heroku 应用和thor docs:download使用再把提交推到 main 分支触发 Heroku 部署。docs/maintainers.md 中的 Updating docs 与 Deploying DevDocs 两节定义了这条完整路径本文把它整理成一条可照做的操作链。前提S3 与 Heroku 访问权限根据 docs/maintainers.md 的 Setup requirements部署 DevDocs 需要获得 Heroku 访问权限并在本机配置好 Heroku CLI获得 DevDocs 的 S3 凭证安装并配置 AWS CLImacOS 上可用brew install awscli。配置时必须添加一个名为devdocs的命名 profileaws configure --profile devdocs文档同时说明一份文档由成千上万个小文件组成AWS CLI 默认的 10 个并发请求偏低调高可以显著加快thor docs:uploadaws configure set s3.max_concurrent_requests 100 --profile devdocs aws configure set s3.max_queue_size 10000 --profile devdocs替代路径可选也可以用 rclone 的 s3 后端代替 AWS CLI此时给各命令加上--rclone选项。另外文档提醒如果这是你的第一次部署确保另一位维护者在场协助。上传前的本地准备thor docs:upload只能上传已生成且已打包的文档。按 lib/tasks/docs.thor 中upload的实现第 183–194 行命令会先做两项检查public/docs/doc.path目录存在文档生成产物public/docs/doc.path.tar.gz存在文档包。任一缺失时命令会报错并停止。例如包缺失时会提示ERROR: package for slug documentation not found. Run thor docs:package slug to create it.此时先运行thor docs:package补齐打包再重新上传也可以用thor docs:generate docversion --package在生成时自动打包。因此上传前的完整准备是参考 .github/CONTRIBUTING.md 的 Updating existing documentations修改 scraper 文件中的版本/发布配置必要时更新options[:attribution]、图标与self.links用thor docs:generate docversion重新生成确认没有报错、分类仍然合理提交变更。维护者有快捷命令thor docs:commit doc它会把 scraper 与assets/的文件改动提交为一个 commit提交信息包含文档更新到的最新版本漏掉的文件可用git commit --amend补入。两点约束来自 docs/maintainers.mdcommit 可以在thor docs:upload之前做但在文件上传到生产并完成应用部署之前不要推送到 GitHubpublic/docs/docs.json的改动永远不要提交——它只反映本机下载/生成过哪些文档在干净的git clone下应为空。执行 thor docs:uploadthor docs:upload一次执行两个操作见 docs/maintainers.md 与 lib/tasks/docs.thor 第 196–231 行将指定文档的文件与 S3 同步aws s3 sync ... s3://devdocs-documents/doc.path --delete --profile devdocs供 Heroku 应用使用将文档包上传到 S3 bundle 区aws s3 cp ... s3://devdocs-downloads/doc.path.tar.gz --profile devdocs供thor docs:download使用。常用形式# 只上传指定文档名称/版本写法与 docs:package 相同如 rails5.2 thor docs:upload rails5.2 # 上传本机已打包public/docs 下存在 .tar.gz的全部文档 thor docs:upload --packaged # 不实际上传仅测试配置与命令效果 thor docs:upload --dryrun用--dryrun先验证一次 AWS CLI 配置与命令效果是维护者文档明确给出的做法。命令正常运行时控制台会依次出现[S3] Begin syncing.、每个文档的[S3] Syncing path...、[S3] Done syncing.随后进入[S3 bundle] Begin uploading./[S3 bundle] Done uploading.阶段。关键约束文档强调 the app should always be deployed immediately after this command has finished running——即只有在有能力且准备好立即部署 DevDocs 时才应运行这条命令。部署到 Heroku上传完成后向 DevDocs 的 main 分支推送或合并包含更新的 PR。按 .github/workflows/deploy-heroku.yml这会触发 GitHub Action先运行测试bundle exec rake测试通过后安装 Heroku CLI、执行heroku stack:set heroku-26与heroku git:remote再git push heroku HEAD:main完成自动部署。这里存在本地与生产环境的依赖关系docs/maintainers.mdthor docs:download从生产环境下载文件所以新增文档的 PR 必须在文件先上传到生产之后再合并推送否则docs:download会在新文档上失败docker 容器无法正常构建。这也是先 upload、后 push顺序的原因。验证与回滚部署完成后的验证方式针对文档更新场景见 Deploying DevDocs需要等几秒让 service worker 完成对新资产的缓存缓存完成后页面会出现 DevDocs has been updated 通知此时刷新页面即可看到新内容。如果部署出问题文档给出的处理路径是heroku rollback回滚到上一版本应用也可通过 Heroku UI 操作。但文档特别提醒heroku rollback不会回退已通过thor docs:upload上传的文档文件。正确做法是尽快修复问题并重新部署需要时联系其他维护者协助。收尾清理本地产物部署并验证通过后运行thor docs:clean它会删除所有文档包文件public/docs下的.tar.gz上传后不再需要以及 scraper 缓存在tmp/cache中的响应。至此一次更新文档 → 上传 S3 → 部署 Heroku的完整流程结束。【免费下载链接】devdocsAPI Documentation Browser项目地址: https://gitcode.com/GitHub_Trending/de/devdocs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考