Environment Variables Configuration Guide

Rin requires two types of environment variables: Variables (plaintext) and Secrets (encrypted).

Quick Reference

Type	Storage	Purpose	Examples
Variables	Plaintext in `wrangler.toml`	Configuration parameters, feature flags	Bucket name, cache mode
Secrets	Encrypted in Cloudflare	Sensitive credentials, keys	API keys, passwords, tokens

Variables (Plaintext)

These variables are stored in plaintext in wrangler.toml or GitHub Actions and control feature flags and basic parameters.

Site Configuration

Variable	Required	Description	Default
`NAME`	No	Site name & title	Rin
`DESCRIPTION`	No	Site description	A lightweight personal blogging system
`AVATAR`	No	Site avatar URL	-
`PAGE_SIZE`	No	Default pagination size	5
`RSS_ENABLE`	No	Enable RSS link	false
`FRONTEND_URL`	No	Canonical site origin for sitemap.xml and robots.txt generation (recommended for multi-domain deployments)	request origin

Tip

Site configuration can be modified via the Settings Page after deployment. Environment variables serve as initial defaults only.

Storage Configuration

Variable	Required	Description	Default	Example
`S3_FOLDER`	Yes	Image storage path	images/	`images/`
`S3_CACHE_FOLDER`	No	Cache file path	cache/	`cache/`
`S3_BUCKET`	Yes	S3 bucket name	-	`my-bucket`
`S3_REGION`	Yes	S3 region (use 'auto' for R2)	-	`auto`
`S3_ENDPOINT`	Yes	S3 endpoint URL	-	`https://xxx.r2.cloudflarestorage.com`
`S3_ACCESS_HOST`	No	Public access URL	Same as S3_ENDPOINT	`https://cdn.example.com`
`S3_FORCE_PATH_STYLE`	No	Force path-style URLs	false	`false`

Feature Flags

Variable	Required	Description	Default	Recommended
`CACHE_STORAGE_MODE`	No	Cache mode: s3/database	s3	database
`WEBHOOK_URL`	No	Comment notification webhook	-	-
`RSS_TITLE`	No	RSS feed title	Rin Development	-
`RSS_DESCRIPTION`	No	RSS feed description	Development Environment	-

For New Users

We recommend setting CACHE_STORAGE_MODE to database to reduce deployment complexity without additional S3 cache configuration.

Secrets (Encrypted)

These sensitive values must be configured as Cloudflare Workers Secrets, entered via CLI during deployment or set in advance.

Authentication

Variable	Required	Description	How to Obtain
`ADMIN_USERNAME`	Conditional	Username for password login	Set yourself
`ADMIN_PASSWORD`	Conditional	Password for password login	Set yourself
`RIN_GITHUB_CLIENT_ID`	Conditional	GitHub OAuth client ID	GitHub OAuth App settings
`RIN_GITHUB_CLIENT_SECRET`	Conditional	GitHub OAuth client secret	GitHub OAuth App settings
`RIN_GITEE_CLIENT_ID`	Conditional	Gitee OAuth client ID	Gitee OAuth App settings
`RIN_GITEE_CLIENT_SECRET`	Conditional	Gitee OAuth client secret	Gitee OAuth App settings
`RIN_QQ_TOKEN`	Conditional	Xinyue QQ login token	Apply at https://qq.wch666.com/
`RIN_WECHAT_APPID`	Conditional	聚合登录 WeChat App ID	Apply at https://login.mapay.cn/
`RIN_WECHAT_APPKEY`	Conditional	聚合登录 WeChat App Secret	Apply at https://login.mapay.cn/
`EMAIL_SEND_URLS`	Conditional	MailPort send URLs (JSON array; a single sender may omit the array brackets — see the format notes below)	Deploy MailPort and read the sender page
`EMAIL_SEND_KEYS`	Conditional	MailPort API keys (JSON array or a single string, matched with `EMAIL_SEND_URLS` in order)	Generated on the MailPort sender page
`EMAIL_RESEND_URL`	Conditional	Legacy email relay service URL (Vercel-deployed Rin-Email project); used as fallback when `EMAIL_SEND_URLS` is not set	Deploy Rin-Email to Vercel to get the URL
`EMAIL_RESEND_PASS`	Conditional	Legacy email relay service auth password (same as EMAIL_PASS in Vercel project)	Set yourself
`JWT_SECRET`	Yes	JWT signing key (any random string)	Generate yourself

Email Relay Architecture

Cloudflare Workers does not support raw TCP SMTP. Email verification is handled by the MailPort sending service:

Deploy MailPort, create a sender, and configure a delivery method (SMTP / HTTP API / Outlook or Gmail OAuth)
Rin blog receives a verification code request and calls the endpoint from EMAIL_SEND_URLS, authenticating with Authorization: Bearer <EMAIL_SEND_KEYS>
Allowed recipient domains are managed in the MailPort sender configuration

EMAIL_SEND_URLS and EMAIL_SEND_KEYS are matched one-to-one in order and polled: if the first endpoint fails, the next one is tried; an error is raised only when all of them fail.

When EMAIL_SEND_URLS is not set, Rin falls back to the legacy EMAIL_RESEND_URL / EMAIL_RESEND_PASS (Rin-Email project).

Format

EMAIL_SEND_URLS is a JSON array of send URLs; each element is a MailPort sender's full send endpoint, shaped like https://<your-domain>/api/<sender-id>/send. EMAIL_SEND_KEYS holds the matching API keys and can also be a JSON array.

With a single sender, EMAIL_SEND_KEYS may be a plain string, no array brackets needed:

EMAIL_SEND_URLS=["https://your-mailport.vercel.app/api/xxxxxx/send"]
EMAIL_SEND_KEYS=your-api-key

With multiple senders that each have their own key, the two arrays are matched by index:

EMAIL_SEND_URLS=["https://mail-a.vercel.app/api/aaaaaa/send","https://mail-b.vercel.app/api/bbbbbb/send"]
EMAIL_SEND_KEYS=["key-for-a","key-for-b"]

With multiple senders sharing one key, write a single key that is applied to every endpoint:

EMAIL_SEND_URLS=["https://mail-a.vercel.app/api/aaaaaa/send","https://mail-b.vercel.app/api/bbbbbb/send"]
EMAIL_SEND_KEYS=shared-api-key

When EMAIL_SEND_KEYS provides multiple values, the count must match EMAIL_SEND_URLS (or provide a single shared key); a mismatch fails at send time.

Captcha Image (Human Verification)

The self-service friend-link flow (apply / modify / delete via email) requires a captcha check on the applicant's first email to prevent automated abuse:

The applicant sends "友链申请 / 友链修改 / 友链删除" (apply / modify / delete) to the receiving address
Rin generates a captcha image (4 characters with noise lines and dots) and sends it as an inline image to the applicant
The applicant replies in a new email containing only those 4 characters
After the captcha passes, the normal JSON template flow continues

This relies on MailPort's inline-image support and requires no new environment variables — it reuses EMAIL_SEND_URLS + EMAIL_SEND_KEYS. The legacy Rin-Email relay has no inline-image support; if it is still in use, the captcha step is skipped automatically.

Authentication Required

You must configure at least one of the following authentication methods:

GitHub OAuth (RIN_GITHUB_CLIENT_ID + RIN_GITHUB_CLIENT_SECRET)
Gitee OAuth (RIN_GITEE_CLIENT_ID + RIN_GITEE_CLIENT_SECRET)
QQ Login (RIN_QQ_TOKEN)
WeChat Login (RIN_WECHAT_APPID + RIN_WECHAT_APPKEY)
Email Verification Code Login (EMAIL_SEND_URLS + EMAIL_SEND_KEYS, or the legacy EMAIL_RESEND_URL + EMAIL_RESEND_PASS)
Username/Password (ADMIN_USERNAME + ADMIN_PASSWORD)

Otherwise you cannot access the admin panel.

QQ Callback URL

The QQ login callback URL is fixed to https://<your-domain>/api/user/xinyueqq/callback. You must configure the same callback URL for the token in Xinyue. The path is hardcoded in the code, no env var needed.

S3 Storage Credentials

Variable	Required	Description	How to Obtain
`S3_ACCESS_KEY_ID`	Conditional	S3 access key ID	R2 API Token ID
`S3_SECRET_ACCESS_KEY`	Conditional	S3 secret access key	R2 API Token

Tip

When CACHE_STORAGE_MODE=database, S3 storage credentials are optional and only needed for image uploads.

Cloudflare Bindings (Not Environment Variables)

The following are Cloudflare Worker bindings configured in wrangler.toml, not environment variables:

Binding	Type	Description
`DB`	D1 Database	Database binding
`ASSETS`	R2 / Static Assets	Static assets binding (optional)
`AI`	AI	Cloudflare AI model binding

GitHub Actions Variables

When using GitHub Actions for automated deployment, configure these in your Repository settings:

Repository Variables (Settings → Secrets and variables → Variables)

Variable	Required	Description	Default
`NAME`	No	Site name	Rin
`DESCRIPTION`	No	Site description	A lightweight personal blogging system
`AVATAR`	No	Site avatar URL	-
`PAGE_SIZE`	No	Pagination size	5
`RSS_ENABLE`	No	Enable RSS	false
`CACHE_STORAGE_MODE`	No	Cache mode	s3
`S3_CACHE_FOLDER`	No	Cache file path	cache/
`S3_FOLDER`	No	Image storage path	images/
`S3_REGION`	No	S3 region	auto
`S3_FORCE_PATH_STYLE`	No	Force path-style	false
`RSS_TITLE`	No	RSS title	Rin Development
`RSS_DESCRIPTION`	No	RSS description	Development Environment
`WEBHOOK_URL`	No	Comment notification webhook	-
`REPO_WORKER_NAME`	No	Worker name	rin-server
`REPO_DB_NAME`	No	D1 database name	rin
`R2_BUCKET_NAME`	No	R2 bucket name	-
`EMAIL_SEND_URLS`	Conditional	MailPort send URLs (JSON array)	-

Repository Secrets (Settings → Secrets and variables → Secrets)

Variable	Required	Description
`CLOUDFLARE_API_TOKEN`	Yes	Cloudflare API token
`CLOUDFLARE_ACCOUNT_ID`	Yes	Cloudflare account ID
`S3_ENDPOINT`	Conditional	S3/R2 endpoint URL
`S3_ACCESS_HOST`	Conditional	S3/R2 access domain
`S3_BUCKET`	Conditional	S3 bucket name
`S3_ACCESS_KEY_ID`	Conditional	S3 access key ID
`S3_SECRET_ACCESS_KEY`	Conditional	S3 secret access key
`JWT_SECRET`	Yes	JWT signing key
`RIN_GITHUB_CLIENT_ID`	Conditional	GitHub OAuth ID
`RIN_GITHUB_CLIENT_SECRET`	Conditional	GitHub OAuth Secret
`RIN_GITEE_CLIENT_ID`	Conditional	Gitee OAuth ID
`RIN_GITEE_CLIENT_SECRET`	Conditional	Gitee OAuth Secret
`RIN_QQ_TOKEN`	Conditional	Xinyue QQ login token
`ADMIN_USERNAME`	Conditional	Admin username
`ADMIN_PASSWORD`	Conditional	Admin password
`EMAIL_SEND_KEYS`	Conditional	MailPort API keys (matched with `EMAIL_SEND_URLS` in order)

Local Development Environment

For local development, use .env file (see .env.example):

# Site Configuration
NAME="My Blog"
DESCRIPTION="A personal blog"
AVATAR=https://example.com/avatar.png
PAGE_SIZE=5
RSS_ENABLE=false

# S3 Storage (R2 or MinIO)
S3_FOLDER=images/
S3_CACHE_FOLDER=cache/
S3_BUCKET=my-bucket
S3_REGION=auto
S3_ENDPOINT=https://xxx.r2.cloudflarestorage.com
S3_ACCESS_HOST=https://cdn.example.com
S3_FORCE_PATH_STYLE=false

# Cache Mode
CACHE_STORAGE_MODE=database

# Webhook
WEBHOOK_URL=

# RSS
RSS_TITLE=My Blog
RSS_DESCRIPTION=My Personal Blog

# Authentication (configure at least one)

# Option 1: GitHub OAuth
RIN_GITHUB_CLIENT_ID=xxx
RIN_GITHUB_CLIENT_SECRET=xxx

# Option 2: Gitee OAuth
RIN_GITEE_CLIENT_ID=xxx
RIN_GITEE_CLIENT_SECRET=xxx

# Option 3: Xinyue QQ Login
RIN_QQ_TOKEN=xxx

# Option 4: 聚合登录 WeChat
RIN_WECHAT_APPID=xxx
RIN_WECHAT_APPKEY=xxx

# Option 5: Email Verification Code Login
# After deploying MailPort (https://github.com/wool-hmq/mailport), configure these variables:
# - MailPort project: create a sender, configure the delivery method and allowed domains, generate an API key
# - Rin blog env vars: EMAIL_SEND_URLS is a JSON array of send URLs, EMAIL_SEND_KEYS holds the matching keys
#   Single sender (the key may be a plain string):
EMAIL_SEND_URLS=["https://your-mailport.vercel.app/api/xxxxxx/send"]
EMAIL_SEND_KEYS=your-mailport-api-key
#   Multiple senders (keys matched by index, or one shared key):
# EMAIL_SEND_URLS=["https://mail-a.vercel.app/api/aaaaaa/send","https://mail-b.vercel.app/api/bbbbbb/send"]
# EMAIL_SEND_KEYS=["key-for-a","key-for-b"]
# Legacy fallback (used only when the two variables above are not set; requires deploying Rin-Email to Vercel):
EMAIL_RESEND_URL=https://your-rin-email.vercel.app/api/send
EMAIL_RESEND_PASS=your-email-pass

# Option 6: Username/Password Login
ADMIN_USERNAME=admin
ADMIN_PASSWORD=secure_password

# JWT Secret (required)
JWT_SECRET=random_secret_key

# S3 Credentials (required if using S3 storage)
S3_ACCESS_KEY_ID=xxx
S3_SECRET_ACCESS_KEY=xxx

Minimal Deployment Checklist

Variable	Type	Required
`JWT_SECRET`	Secret	Yes
`ADMIN_USERNAME`	Secret	Yes
`ADMIN_PASSWORD`	Secret	Yes
`S3_FOLDER`	Variable	Yes
`S3_BUCKET`	Variable	Yes
`S3_REGION`	Variable	Yes
`S3_ENDPOINT`	Variable	Yes
`S3_ACCESS_KEY_ID`	Secret	Conditional
`S3_SECRET_ACCESS_KEY`	Secret	Conditional

Full Configuration (All Features)

Includes site config, all OAuth providers, email login, S3 storage, webhook, and RSS.

FAQ

Q: Do I need S3 config when using `CACHE_STORAGE_MODE=database`?

No. database mode stores cache in D1 database without S3/R2. However, S3 config is still required if you need image uploads.

Yes. Configure credentials for multiple methods and the frontend will display corresponding login buttons automatically.

Email verification is handled by the MailPort sending service:

Deploy MailPort, create a sender, and configure a delivery method (SMTP / HTTP API / Outlook or Gmail OAuth)
Generate an API key on the MailPort sender page, and configure allowed recipient domains as needed
In your Cloudflare Worker, configure:
- EMAIL_SEND_URLS = the full send endpoint(s) of your MailPort sender (JSON array, multiple allowed)
- EMAIL_SEND_KEYS = the matching API key(s), paired with the endpoints in order

EMAIL_SEND_URLS and EMAIL_SEND_KEYS are polled in order: if the first endpoint fails, the next one is tried; an error is raised only when all of them fail. When these two variables are not set, Rin falls back to the legacy EMAIL_RESEND_URL / EMAIL_RESEND_PASS (Rin-Email).

Q: What JSON format do `EMAIL_SEND_URLS` and `EMAIL_SEND_KEYS` use?

EMAIL_SEND_URLS is a JSON array of send URLs, each shaped like https://<your-domain>/api/<sender-id>/send. EMAIL_SEND_KEYS holds the keys matched with them in order.

With a single sender, the key may be a plain string:

EMAIL_SEND_URLS=["https://your-mailport.vercel.app/api/xxxxxx/send"]
EMAIL_SEND_KEYS=your-api-key

With multiple senders that each have their own key, the arrays are matched by index:

EMAIL_SEND_URLS=["https://mail-a.vercel.app/api/aaaaaa/send","https://mail-b.vercel.app/api/bbbbbb/send"]
EMAIL_SEND_KEYS=["key-for-a","key-for-b"]

With multiple senders sharing one key, write a single key:

EMAIL_SEND_URLS=["https://mail-a.vercel.app/api/aaaaaa/send","https://mail-b.vercel.app/api/bbbbbb/send"]
EMAIL_SEND_KEYS=shared-api-key

The number of keys must match the number of URLs, or provide a single shared key; a mismatch fails at send time.

Q: How to restrict allowed email domains?

Add the allowed domains to the "allowed recipient domains" list in your MailPort sender configuration. Only recipients on those domains will be delivered to.

Leave the list empty to allow all domains.

Q: Which delivery methods does MailPort support?

MailPort supports the following delivery methods:

SMTP: any SMTP provider (163 Mail, QQ Mail, Gmail, etc.)
HTTP API: forward to a custom HTTP endpoint
Outlook OAuth2 / Gmail OAuth2: send without app passwords

See the MailPort project documentation.

#Environment Variables Configuration Guide

#Quick Reference

#Variables (Plaintext)

#Site Configuration

#Storage Configuration

#Feature Flags

#Secrets (Encrypted)

#Authentication

#S3 Storage Credentials

#Cloudflare Bindings (Not Environment Variables)

#GitHub Actions Variables

#Repository Variables (Settings → Secrets and variables → Variables)

#Repository Secrets (Settings → Secrets and variables → Secrets)

#Local Development Environment

#Minimal Deployment Checklist

#Username/Password Login Only (Minimal Config)

#Full Configuration (All Features)

#FAQ

#Q: Do I need S3 config when using CACHE_STORAGE_MODE=database?

#Q: Can I enable multiple login methods simultaneously?

#Q: How to set up email verification code login?

#Q: What JSON format do EMAIL_SEND_URLS and EMAIL_SEND_KEYS use?

#Q: How to restrict allowed email domains?

#Q: Which delivery methods does MailPort support?