ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

使用 Kamal 部署 Fizzy:从裸机到生产环境的一键化部署指南

使用 Kamal 部署 Fizzy:从裸机到生产环境的一键化部署指南 使用 Kamal 部署 Fizzy从裸机到生产环境的一键化部署指南【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzyFizzy 是一款开源的看板Kanban协作工具代码库采用 Rails 8 构建并原生支持通过 Kamal 完成生产部署。本文基于仓库内 部署说明文档 与 config/deploy.yml 等真实配置完整讲解从 fork 仓库、初始化 Kamal、填写实例化配置、管理密钥到首次kamal setup与后续增量kamal deploy的全流程并深入剖析 SSL、邮件、VAPID 推送密钥、Active Storage 对象存储等关键配置的底层实现。读完本文你将能够独立把 Fizzy 部署到自己的裸机服务器上并具备按需改造其配置的能力。Kamal 部署模式概览Kamal 是 37signals 出品的免 Kubernetes 部署工具它通过 SSH 直连裸机服务器利用 Docker 完成镜像构建、分发与容器编排同时内置 Traefik 反向代理和自动 SSL 证书签发能力。Fizzy 官方推荐用户使用 Kamal 自行部署的原因很直接既能把 Fizzy 跑在自己掌控的服务器上又保留了随意修改其代码的自由度。值得一提的是37signals 内部正是用 Kamal 部署 Fizzy 的 SaaS 版本其生产配置封装在fizzy-saas引擎中而本仓库自带了一份可直接改造的入门级部署文件 config/deploy.yml这也是 Kamal 默认查找部署配置的位置。从仓库依赖看Kamal 已作为开发依赖声明在 Gemfile 中gem kamal, require: false因此你无需全局安装 Kamal直接通过项目内的bin/kamal即可调用。整体部署步骤可归纳为四步Fork 仓库运行kamal init初始化生成.kamal目录及.kamal/secrets等配置文件按需修改 config/deploy.yml 与.kamal/secrets运行kamal setup完成首次部署。下面逐步展开。第一步Fork 仓库并准备本地环境为了让 Fizzy 的各项设置针对你自己的实例定制建议先从创建仓库的 GitHub fork 开始。这样你可以把改动提交到自己的 fork 中并持续跟踪历史之后也可以随时与主仓库重新同步拉取上游的新变更。Fork 完成后在 fork 目录内运行bin/setup确保本地依赖gem、数据库等全部就绪bin/setup这一步保证了后续本地调试、密钥生成等操作有完整的运行环境。第二步初始化 Kamal在 fork 仓库根目录执行kamal init该命令会生成.kamal目录以及 Kamal 运行所需的配置骨架其中最重要的产物是.kamal/secrets——所有环境变量密文都将存放在这里。由于后续该文件会写入真实凭据务必确认它不会被提交进版本库详见下文密钥管理小节。注意kamal init生成的是骨架文件而本仓库已经预先写好了面向 Fizzy 的 config/deploy.yml 起点配置因此初始化后你只需要编辑其中About your deployment相关段落无需从零编写。第三步编辑部署配置核心config/deploy.yml 的实例化字段config/deploy.yml 已经把大部分通用配置准备妥当你需要修改的字段都集中在文件头部注释标记的#-- About your deployment --#区块。逐项说明如下配置路径用途说明servers/web目标服务器主机名填入你部署目标的域名或 IP需可通过ssh访问ssh/userSSH 登录用户若以root登录可保持默认使用其他用户时在此设置proxy/ssl是否启用自动 SSL设为true时 Kamal 借助 Traefik Lets Encrypt 自动签发证书不需要 SSL 可设为falseproxy/host自动 SSL 的域名与servers/web保持一致Kamal 据此申请证书env/clear/BASE_URL实例公开 URL例如https://fizzy.example.com用于生成邮件、分享链接等外链env/clear/MAILER_FROM_ADDRESS发件人地址通常使用与 Fizzy 同域名的邮箱env/clear/SMTP_ADDRESSSMTP 服务器地址可使用 SendGrid、Postmark 等第三方服务按其文档填写env/clear/MULTI_TENANT是否允许注册多个账号默认false单账号实例设为true允许他人自助注册多个账号仓库自带的模板值如下供对照servers: web: - fizzy.example.com # 改成你的服务器域名 ssh: user: root # 如果你用其他用户名 SSH 登录改这里 proxy: ssl: true # 不需要 SSL 就改成 false host: fizzy.example.com env: clear: BASE_URL: https://fizzy.example.com MAILER_FROM_ADDRESS: supportexample.com SMTP_ADDRESS: mail.example.com MULTI_TENANT: false SOLID_QUEUE_IN_PUMA: true # 后台任务与应用同进程运行模板中SOLID_QUEUE_IN_PUMA: true意味着 Fizzy 使用 Solid Queue 在 Puma 进程内运行后台任务无需单独部署 worker 容器——这与 config/environments/production.rb 中config.active_job.queue_adapter :solid_queue的实现一致属于开箱即用的单机部署形态。邮件发送的底层实现SMTP_ADDRESS等变量并非只被 deploy.yml 引用它们会在 Rails 启动时被生产环境配置真正消费。config/environments/production.rb 中只要检测到SMTP_ADDRESS存在就会启用:smtp投递方式并组装smtp_settings同时支持更多可选的 SMTP 环境变量SMTP_PORT默认按是否启用SMTP_TLS自动取465或587SMTP_DOMAINHELO 域名SMTP_USERNAME/SMTP_PASSWORD认证凭据SMTP_AUTHENTICATION认证方式默认plainSMTP_TLStrue启用 TLSSMTP_SSL_VERIFY_MODEOpenSSL 校验模式。同理BASE_URL会被解析为default_url_optionshost/protocol/port同时注入 Action Mailer 的default_url_options从而保证邮件与外部引用中的链接指向你的公开域名见 config/environments/production.rb。密钥管理.kamal/secretsFizzy 还要求一组环境变量其中部分包含敏感凭据。最直接的做法是把它们写进.kamal/secrets文件。由于该文件存放真实凭据务必不要提交到版本库——建议把文件名加入.gitignore以防误提交。如果你使用 1Password 等密码管理器也可以选择把密钥托管在那里具体做法可参考 Kamal 官方文档的环境变量/Secrets 章节。.kamal/secrets的推荐内容模板如下SECRET_KEY_BASE12345 VAPID_PUBLIC_KEYsomething VAPID_PRIVATE_KEYsomethingelse SMTP_USERNAMEemail-provider-username SMTP_PASSWORDemail-provider-password各凭据的获取方式SECRET_KEY_BASE一个足够长的随机串运行bin/rails secret即可生成合规值SMTP_USERNAME/SMTP_PASSWORD你的 SMTP 服务器有效凭据若使用第三方邮件服务按其文档取值VAPID_PUBLIC_KEY/VAPID_PRIVATE_KEY用于 Web Push 推送通知的密钥对。进入开发控制台生成bin/rails cvapid_key WebPush.generate_key puts VAPID_PRIVATE_KEY#{vapid_key.private_key} puts VAPID_PUBLIC_KEY#{vapid_key.public_key}这两把密钥对应仓库内 config/initializers/vapid.rb 等推送配置仓库同时提供vapid.rb、web_push.rb、push_notifications.rb等初始化器浏览器推送订阅与通知下发都依赖它们因此必须成对配置并保持一致。完成上述修改后将改动提交到你的 fork 中保存。第四步首次部署与日常更新首次部署kamal setup一切就绪后执行首次部署bin/kamal setupsetup会在目标服务器上完成一整套初始化按需安装 Docker、构建 Fizzy 应用镜像、推送并启动容器、配置 Traefik 反向代理与自动 SSL最终把应用跑起来。首次部署所依赖的应用镜像由仓库根目录的 Dockerfile 构建它采用多阶段构建基础镜像安装libjemalloc2、libvips、sqlite3等运行时依赖并默认启用 jemalloc 内存分配器构建阶段预编译 bootsnap 与资产使用SECRET_KEY_BASE_DUMMY1规避对主密钥的依赖最终阶段以非 root 用户UID/GID 1000运行入口脚本 bin/docker-entrypoint 会在启动 Rails server 前自动执行db:prepare即必要时建库或迁移随后经由 Thruster./bin/thrust对外提供 HTTP 服务。这意味着你在服务器上甚至无需手动执行db:migrate。日常部署kamal deploy首次setup完成之后服务器环境已经就绪后续更新不再需要重复初始化。每次推送新代码后只需运行bin/kamal deploydeploy会增量构建新镜像并滚动替换容器同时 config/deploy.yml 中配置的asset_path: /rails/public/assets会桥接新旧版本的指纹化静态资源避免部署切换瞬间的 404。仓库还在 config/deploy.yml 里预置了若干实用别名方便日常运维bin/kamal console # 进入生产环境 Rails console bin/kamal shell # 进入应用容器 shell bin/kamal logs # 跟踪应用日志 bin/kamal dbc # 进入数据库 console含密码第五步配置文件存储Active StorageFizzy 生产环境默认使用本地磁盘服务保存附件。若想切换为 config/storage.yml 中定义的其他服务只需设置环境变量ACTIVE_STORAGE_SERVICE。该变量由 config/environments/production.rb 读取当config.active_storage.service尚未被设置例如未被fizzy-saas覆盖时ENV.fetch(ACTIVE_STORAGE_SERVICE, local).to_sym决定最终使用的存储服务。说明仓库根目录的 config/storage.yml 是一个加载器它根据是否运行在 SaaS 模式选择实际的服务定义文件自托管场景下加载的是 config/storage.oss.yml其中内置了test、local、devminio与s3四种服务。下文包含的s3服务即指 config/storage.oss.yml 中的s3定义。使用内置 S3 服务启用 S3 需要设置以下环境变量ACTIVE_STORAGE_SERVICEs3S3_ACCESS_KEY_ID访问密钥 IDS3_BUCKET存储桶名默认fizzy-#{Rails.env}-activestorageS3_REGION区域默认us-east-1S3_SECRET_ACCESS_KEY访问密钥CSP_CONNECT_SRC内容安全策略中允许的connect-src来源其中CSP_CONNECT_SRC并非存储服务本身的参数而是用于打通 CSP 限制仓库在 config/initializers/content_security_policy.rb 中通过policy.connect_src :self, *sources.(:connect_src)将CSP_CONNECT_SRC环境变量空格分隔的来源列表合并进页面级 CSP 策略否则浏览器会拦截对 S3 端点的请求。该初始化器也支持CSP_DEFAULT_SRC、CSP_SCRIPT_SRC、CSP_IMG_SRC等一系列同类变量可整体调整生产环境的 CSP。可选兼容 S3 协议的存储端点若使用 MinIO、Ceph RGW、FlashBlade 等 S3 兼容服务还可追加S3_ENDPOINT自定义端点地址S3_FORCE_PATH_STYLEtrue强制 path-style 寻址S3_REQUEST_CHECKSUM_CALCULATION请求校验和计算策略默认when_supportedS3_RESPONSE_CHECKSUM_VALIDATION响应校验和校验策略默认when_supported这些变量在 config/storage.oss.yml 中一一对应地注入s3服务定义其中force_path_style只有显式等于字符串true时才启用region缺省为us-east-1签名器所需。仓库开发环境中的devminio服务还展示了另一组可行的写法它把request_checksum_calculation/response_checksum_validation设为when_required以规避某些对象存储如 FlashBlade不支持 CRC64NVME 校验和的情况——生产环境遇到兼容性问题时可参照该模式调整上述两个可选变量。持久化数据卷自托管场景默认使用 SQLite 数据库见 config/database.yml 相关配置因此数据持久化至关重要。config/deploy.yml 声明了一个命名卷volumes: - fizzy_storage:/rails/storage它把容器内/rails/storageSQLite 数据库文件与本地 Active Storage 文件所在目录挂载为持久卷避免容器重建导致数据丢失。官方注释建议将其改为带离服务器备份的挂载卷路径如 NFS 或云盘挂载点并做好定期备份。小结Fizzy Kamal 的组合把自托管部署压缩到了改配置、装密钥、跑两条命令的粒度阶段命令/操作关键文件准备Fork 仓库 bin/setup—初始化kamal init.kamal/secrets配置填写实例化字段config/deploy.yml密钥生成并写入凭据.kamal/secrets勿入库首次部署bin/kamal setupDockerfile、bin/docker-entrypoint日常更新bin/kamal deployconfig/deploy.yml附件存储设置ACTIVE_STORAGE_SERVICEconfig/storage.oss.yml部署后如需继续深入可进一步阅读仓库内的 docs/docker-deployment.md 了解纯 Docker 手工部署的替代方案以及 config/environments/production.rb 了解全部可调环境变量含日志级别、SSL 开关、缓存与队列等。从源码到配置Fizzy 的自托管路径是完整且可验证的——现在就可以 fork 一份跑起你自己的看板实例。【免费下载链接】fizzyKanban as it should be. Not as it has been.项目地址: https://gitcode.com/GitHub_Trending/fizzy2/fizzy创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表