本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
生产环境检查清单
在向用户和其他服务器开放服务器之前,请逐项检查这份清单;部署发生变化后也要再检查一遍。有些设置在服务器联邦之后就无法更改,而有些失误(例如丢失密钥加密密钥)根本无法挽回。
每一项都说明了它为什么重要、如何验证,以及详细信息在哪里。先从自动检查的部分开始:
my config check # the configuration, and the settings that do not suit productionmy config check -instance # also the instance settings in the databasemy config check 检查什么
Section titled “my config check 检查什么”在 production 配置档(profile 的默认值)下,my config check 先验证每一项设置,然后检查这些有效的设置是否适合生产实例。发现的问题分为两组列出,每组前面有一段使用进程区域设置语言的摘要,每个问题附有英文的技术细节:
- 错误会让
my config check以 1 退出。它们是会破坏生产实例或削弱其安全性的设置:- 其他服务器无法访问的
host或account_domain:带端口、localhost、不含点的名称,或者属于保留给本地使用或测试的顶级域名的名称(.localhost、.local、.test、.example、.invalid、.internal、.home.arpa)。 - 使用
http的web_origin。 - 把数据库放在内存中的 SQLite
database_url。 - 不是随机生成的
kek,例如全为零或由同一个字节重复组成。 - 属于 CAPTCHA 服务公开的测试密钥的
captcha站点密钥或密钥。 - 指定了不存在的任务类型的
worker_job_types、worker_job_types_except或队列路由(在所有配置档下都会检查;my job types会列出任务类型)。 - 使用
-instance时,数据库连接池无法满足的worker_job_concurrency。
- 其他服务器无法访问的
- 警告不改变退出码,仍为 0。它们是在开发中很常见、在生产中也可能是有意为之的设置:
mail = none。- SQLite 数据库或
fsblob 存储位于临时目录中(/tmp、/var/tmp、/dev/shm或$TMPDIR)。 queue = inline。- 没有
vapid_private_key。 role不是all时使用stream = hub或kv = memory:它们只在单个进程内有效。- 很可能并非本意的语音设置,例如没有 STUN 或 TURN 的
voice = p2p。 - 位于
http://地址的插件,或者位于https://地址但既没有令牌也没有客户端证书的插件。 - 支付服务商的测试模式密钥。
- 设置了
origin_secret但trusted_proxies为空,以及轮换之后仍然保留着origin_secret_previous。 - 使用
-instance时:未设置的实例文本name、short_description、terms和privacy_policy,未设置的实例设置contact_account、contact_email和security_contact,以及没有规则的服务器。无法连接数据库时,这本身算作一条警告,其余检查仍会继续。
my serve 启动时会把同样的发现记录为警告,但仍然会启动。development 配置档会跳过这些检查;它用于本地开发和测试,绝不要用于供他人使用的实例。
请在与服务器相同的环境中(相同的环境变量、密钥文件和配置文件)运行 my config check,例如作为部署的一个步骤,在新版本接收流量之前运行。
之后无法更改的设置
Section titled “之后无法更改的设置”服务器的域名和用户名的域名
Section titled “服务器的域名和用户名的域名”- 原因:
host是服务器每个 ActivityPub id 的一部分,而其他服务器会保存这些 id。account_domain是用户名(@alice@example.org)的域名。第一个使用数据库的my serve或my命令会把两者记录到数据库中,此后只要配置与之不同,my serve和这些命令就会拒绝运行:联邦之后再更改,会破坏所有关注,以及所有指向该服务器帖子和账号的引用。请在首次启动之前设置好两者。如果在联邦之前发现了错误,可以通过重新创建数据库来修正,这会删除所有行。 - 决定:用户名使用服务器的域名还是另一个域名(例如用户名在
example.org上,服务器在social.example.org上)。单独的用户名域名必须把它的 WebFinger、host-meta 和 NodeInfo 重定向到服务器。 - 验证:
my config check会显示host和account_domain,并报告其他服务器无法访问的域名。当它们与数据库中的值不同时,my config check -instance也会失败,并且不记录任何内容。使用单独的用户名域名时,curl -sI "https://<account_domain>/.well-known/webfinger?resource=acct:<user>@<account_domain>"会以301重定向到https://<host>/.well-known/webfinger?...。 - 详情:运行服务器(联邦端点,以及从另一个域名提供用户名),
host和account_domain。
可通过 https 访问
Section titled “可通过 https 访问”- 原因:其他服务器会通过 443 端口在
https://<host>/获取 id,而浏览器只会通过https发送登录 cookie。 - 验证:从你的网络之外执行
curl -sI https://<host>/health/live返回200,且证书对host有效,并且my config check没有报告关于web_origin、tls、tls_acme_agree_terms或tls_cert_file的错误。curl -sI http://<host>/返回301,重定向到https://<host>/。要么由服务器前面的反向代理、负载均衡器或 CDN 终止 TLS 并完成重定向(在 Docker Compose 中,层compose.caddy.yaml就是这样一个代理),要么由服务器自己完成。使用tls = acme时,my tls status会显示host(以及web_origin的主机,当它与前者不同时)的证书,其签发者不是测试环境的签发者:tls_acme_directory未设置,或指向正式环境的目录。请对证书到期和申请失败设置告警(告警)。使用tls = files时,证书的剩余有效期少于 14 天,my config check会发出警告,而负责续期的任何机制都必须让tls_cert_file和tls_key_file保持最新。 - 详情:运行服务器、由服务器提供 HTTPS、
web_origin、tls。
无法绕过 CDN 访问
Section titled “无法绕过 CDN 访问”- 原因:在前面有 CDN、而服务器自己的地址仍然公开(Cloud Run 上的
*.run.app)时,任何人都可以绕过 WAF 和缓存调用服务器,而且 CDN 自己平台上的调用方可以选择速率限制所看到的客户端 IP。只有在这种情况下才需要:如果防火墙或平台已经限制了谁能连接就不需要,没有 CDN 时也没有什么可绕过的。 - 验证:
origin_secret和origin_secret_header已设置,并且 CDN 为每个主机名都设置了该请求头。curl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/返回403,它的/health/live返回200,而https://<host>/返回200。 - 详情:拒绝没有经过 CDN 的请求,包括它把所有人都锁在外面时如何恢复。
密钥加密密钥(KEK)
Section titled “密钥加密密钥(KEK)”- 原因:KEK 加密所有 actor 的私钥。没有它,服务器就无法签名任何内容,而且无法从数据库中恢复这些私钥:所有账号都必须重新创建,其他服务器也将不再信任它。
- 验证:
- 它是随机生成的(
openssl rand -base64 32);my config check会报告不是随机生成的密钥。 - 它保存在数据库及其备份以外的地方,例如密码管理器或云的密钥存储中,并且至少还有一位运行服务器的人能够取得它。
- 它只通过
MY_KEK或MY_KEK_FILE传给服务器(配置文件拒绝存放机密)。使用 Docker Compose 时,它是文件secrets/kek,不在.env中(Docker Compose 文件)。
- 它是随机生成的(
- 详情:密钥管理。
Web Push 的 VAPID 密钥
Section titled “Web Push 的 VAPID 密钥”- 原因:没有它,服务器就不会发送 Web Push 通知。之后更改它会终止所有订阅,所以只生成一次,并像 KEK 一样妥善保管。
- 验证:未设置
vapid_private_key时,my config check会发出警告。用my config vapid-key生成一个。 - 详情:密钥管理(Web Push 的 VAPID 密钥)。
其他机密不放进代码仓库和镜像
Section titled “其他机密不放进代码仓库和镜像”- 原因:放在代码仓库、容器镜像或配置文件中的机密,会被复制到这些东西所到的每一个地方。
- 验证:
database_url、mail_smtp_password、captcha_secret_key、支付服务商的密钥、valkey_url,以及配置参考中标记为机密的其他所有设置,都来自由平台密钥存储(Docker 或 Kubernetes secret、Secret Manager、Parameter Store)填充的环境变量或<NAME>_FILE文件。配置文件不能存放它们:my config check会拒绝其中的机密。使用 Docker Compose 时,它们来自只有你能读取的.env(chmod 600)。在代码仓库和镜像中搜索这些值,确保没有留下副本。my config check会对每个已设置的机密显示(redacted)。 - 详情:配置参考(Secret 列),CAPTCHA,Stripe,PAY.JP。
实例设置保存在数据库中,可以在服务器运行时通过服务器的管理页面或 my instance set 更改。my config check -instance 会对未设置的文本、联系方式和规则发出警告。
- 名称、简短描述和描述:显示在首页、信息页面(
/about)、链接预览和 NodeInfo 中。在/about上验证。 - 联系方式:
contact_account(用户就服务器事宜联系的账号)和contact_email(用户和其他服务器写信的地址;服务器发出的邮件也会把回复发到这里)。在/about上验证。 - 漏洞联系方式:
security_contact,一个https:或mailto:URI。设置后,服务器会响应/.well-known/security.txt。用curl -s https://<host>/.well-known/security.txt验证。 - 服务条款和隐私政策:
terms和privacy_policy。隐私政策必须列出接收个人数据的服务,例如 CAPTCHA 服务和邮件服务商。验证/about和注册页面上的链接。 - 服务器规则:用户注册时同意的内容,也是审核员执行的内容。用
my instance rule create或在管理页面中添加,并在/about上验证。 - 注册模式:在你更改之前,
registration_mode为approval;根据人们加入的方式,从open、approval、invite或closed中选择。在mail = none时,open的注册也要等待审核员批准。 - 搜索引擎和 AI:在你允许之前,
search_indexing、ai_usage和indexable_default会拒绝两者。验证/robots.txt和/.well-known/tdmrep.json。 - 状态页面:把
status_page_url(这是一项设置而不是实例设置,所以维护期间也会显示该链接)设为位于服务器以外服务上的状态页面。
详情:实例设置,注册,搜索引擎和 AI 爬虫,CAPTCHA(隐私政策中要写什么),隐私政策模板,处理活动记录模板,监控(状态页面)。
- 原因:电子邮件用于验证地址,并发送密码重置邮件和通知。在
mail = none时,没有任何邮件会送达用户。 - 验证:
mail为smtp、ses或plugin,且mail_from是你所控制的域名上的地址;my config check会对mail = none发出警告。mail_from的域名有 SPF、DKIM 和 DMARC 记录,且服务商使用 DKIM 签名。没有这些,邮件会进入垃圾邮件。- 用测试账号注册并收到验证邮件;请求重置密码,并且同样收到邮件。检查收到的邮件头中是否有
spf=pass、dkim=pass和dmarc=pass。 - 使用 SES 时,账号已脱离沙盒,且退信和投诉通知能送达服务器。
- 详情:电子邮件,注册(电子邮件验证)。
- 原因:管理员账号可以更改所有设置、读取私密数据,并停用任何人的账号。
- 验证:
- 每位管理员都已开启双重验证(Web 客户端中的“设置”、“双重验证”),并保存好恢复码。
- 只有需要的人才拥有
admin角色;审核员拥有moderator角色,或者只包含他们所用权限的角色。用my admin role列出他们,并在管理页面上进行审查。
- 详情:管理员和角色,审核(权限和登录恢复)。
- 备份和恢复:数据库、blob 存储(
blob_fs_dir或存储桶)和 KEK 按计划备份到与服务器分开的地方,并且已经演练过恢复到一台全新的服务器:恢复后的服务器能够启动,账号可以登录和发帖。从未恢复过的备份,无法确定它是否可用。数据库和媒体不能放在临时目录中;放在那里时,my config check会发出警告。请参阅密钥管理(备份 KEK)和数据库。 - 监控和告警:外部监控检查
/health/live,并向能够采取行动的人发出告警,同时监视任务队列中的死任务。请参阅监控和运行服务器(健康检查、指标和任务队列)。 - 镜像:实例运行的是按摘要固定的已发布镜像(
ghcr.io/mycroblog/my:0.1.0@sha256:...,来自该版本的发布说明),而不是重启时会变化的镜像,并且其来源已经验证。没有latest标签。升级会有意更改该版本,并遵循升级,一次一个小版本。 - 源代码(AGPL-3.0):服务器必须向每一位使用它的人提供它的源代码。对于未修改的发布版本,请保持
source_url为默认值;当你运行分支或修改过的版本时,请让它指向你自己的源代码。请在/about上验证该链接。请参阅运行服务器(发布源代码)。 - 维护:在需要之前就了解如何让服务器进入维护模式。请参阅维护。
- 原因:其他服务器通过 WebFinger 和 NodeInfo 查找账号,然后获取 actor。如果从外部访问时其中任何一项失败,服务器在联邦宇宙中就是不可见的。
- 从你的网络外部的机器上验证:
curl -s "https://<account_domain>/.well-known/webfinger?resource=acct:<user>@<account_domain>"返回该账号;域名不同时,跟随重定向到host(curl -L)。curl -s https://<host>/.well-known/nodeinfo链接到/nodeinfo/2.1,其中写明了软件及其源代码。curl -s -H 'Accept: application/activity+json' https://<host>/@<user>重定向到 actor 的 id,而该 id 上的 actor 是带有publicKey的 JSON。- 从 Mastodon 或其他服务器上的账号搜索
@<user>@<account_domain>,关注它,并看到新帖子送达。 - 服务器前面的 CDN 不缓存
/ap/*和/@*,除非它遵循Vary: Accept。
- 详情:运行服务器(联邦端点),CDN,中继。
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt