convex-domains

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up a custom domain with your own provider

使用自有服务商设置自定义域名

Walk the user's own registrar through pointing their domain at the Convex app: identify the target (hosting or deployment URL), create the DNS records, attach the custom domain, and rebind the auth origin if the app uses auth.

引导用户通过其域名注册商将域名指向Convex应用：确定目标地址（托管或部署URL）、创建DNS记录、绑定自定义域名，若应用使用认证功能则重新绑定认证源。

Workflow

工作流程

Identify the target: the published site host (for
```
*.convex.app
```
static hosting) or the deployment's HTTP actions URL.
Detect an ALREADY-AUTHENTICATED DNS CLI for the user's provider and OFFER to create the records automatically: Cloudflare →
```
flarectl dns create
```
(note:
```
wrangler
```
itself doesn't manage DNS records) or the CF API via their token env; Route53 →
```
aws route53 change-resource-record-sets
```
; Google Cloud DNS →
```
gcloud dns record-sets create
```
; DigitalOcean →
```
doctl compute domain records create
```
; Vercel DNS →
```
vercel dns add
```
. Check auth read-only first (
```
flarectl user info
```
/
```
aws sts get-caller-identity
```
/
```
doctl account get
```
); show the exact commands and get a yes before running.
If no authed CLI (or the user declines), tell the user exactly which records to create at THEIR registrar: the CNAME (or A/ALIAS at the apex) plus the TXT verification record — with concrete host/value strings, not placeholders.
Attach the domain as a Convex custom domain (dashboard or CLI) and wait for verification; note DNS propagation can take minutes to hours. Verify records landed with
```
dig +short
```
.
If the app uses auth (passkeys/OAuth), rebind the auth origin (SITE_URL / RP_ID / ORIGIN env vars) to the new domain and re-deploy/re-publish.
Verify: the domain serves the app over HTTPS, including the apex → www redirect if configured.

确定目标地址：已发布站点的主机地址（针对
```
*.convex.app
```
静态托管）或部署的HTTP操作URL。
检测用户服务商已认证的DNS CLI，并主动提出自动创建记录：Cloudflare →
```
flarectl dns create
```
（注意：
```
wrangler
```
本身不管理DNS记录）或通过其令牌环境变量调用CF API；Route53 →
```
aws route53 change-resource-record-sets
```
；Google Cloud DNS →
```
gcloud dns record-sets create
```
；DigitalOcean →
```
doctl compute domain records create
```
；Vercel DNS →
```
vercel dns add
```
。先检查只读权限认证（
```
flarectl user info
```
/
```
aws sts get-caller-identity
```
/
```
doctl account get
```
）；显示具体命令并在执行前获得用户确认。
如果没有已认证的CLI（或用户拒绝自动创建），告知用户需在其注册商处创建的具体记录：CNAME（或根域名的A/ALIAS记录）加上TXT验证记录——提供具体的主机/值字符串，而非占位符。
在Convex中绑定该自定义域名（通过控制台或CLI）并等待验证；注意DNS传播可能需要数分钟到数小时。使用
```
dig +short
```
验证记录是否生效。
若应用使用认证功能（密钥/OAuth），将认证源（SITE_URL / RP_ID / ORIGIN环境变量）重新绑定到新域名，并重新部署/发布应用。
验证：域名通过HTTPS提供应用服务，包括已配置的根域名→www域名重定向。

Rules

规则

Never ask for or handle registrar credentials. A CLI already authenticated on the user's machine is fine — the credential stays in the tool; never install a CLI or run its login/auth flow for this, and never echo tokens.
DNS changes on a live domain are user-visible: show the exact commands and confirm before running them; verify afterwards with dig.
Always include the TXT verification record, not just the CNAME.
Rebinding the domain changes the auth origin — re-publish after, or sign-in breaks.
If the user wants Convex to find/buy a domain for them, hand off to
```
labs-acquire-domain
```
.

绝不索要或处理注册商凭证。用户机器上已认证的CLI是可行的——凭证保留在工具中；绝不为此安装CLI或运行其登录/认证流程，绝不回显令牌。
对生效域名进行DNS更改会被用户感知：显示具体命令并在执行前确认；执行后用dig验证。
始终包含TXT验证记录，而非仅CNAME记录。
重新绑定域名会更改认证源——之后需重新发布应用，否则登录功能会失效。
若用户希望Convex帮助查找/购买域名，转交至
```
labs-acquire-domain
```
处理。