SovereignID
文档目录 快速开始

Deployment Checklist

快速开始

首次部署

完成运行环境、数据库、邮件服务、OIDC 密钥和首次登录的基础配置。

这一节用于把 SovereignID 跑起来，并确认它已经具备作为 OIDC Provider 的基础能力。 Gitea、New API 等业务系统接入前，先完成这里的检查。

一、准备运行环境

SovereignID 需要 Python 运行环境、PostgreSQL、Redis 和可用的发信服务。开发环境可以使用本机已有数据库与 Redis； 生产环境建议由统一基础设施提供数据库、缓存、反向代理和 HTTPS 证书。

依赖 用途 建议
PostgreSQL 保存用户、邮箱验证、OAuth2/OIDC 应用与授权数据。 生产环境使用独立数据库，并配置备份。
Redis 作为 Celery broker、result backend 和缓存基础设施。 Web 与 Celery worker 必须连接同一组 Redis。
SMTP 发送登录验证码、邮箱验证和重发验证码邮件。 上线前先用真实邮箱完成一次验证流程。
HTTPS 入口 对外提供稳定的 issuer、登录页和 OIDC 端点。 生产环境不要频繁变更 SOVEREIGNID_ISSUER_URL。

二、配置环境变量

从示例文件复制一份环境变量配置，并按实际部署环境修改。下面只列关键项，完整字段以项目根目录的 .env.example 为准。 

DJANGO_SECRET_KEY=change-me-to-a-long-random-secret
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=id.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://id.example.com

SOVEREIGNID_ISSUER_URL=https://id.example.com

DATABASE_URL=postgres://user:password@postgres:5432/sovereignid
REDIS_URL=redis://:password@redis:6379/0
CELERY_BROKER_URL=redis://:password@redis:6379/1
CELERY_RESULT_BACKEND=redis://:password@redis:6379/2

EMAIL_HOST=smtp.example.com
EMAIL_PORT=465
EMAIL_HOST_USER=notice@example.com
EMAIL_HOST_PASSWORD=change-me
EMAIL_USE_SSL=True
EMAIL_FROM=notice@example.com

PHONE_VERIFICATION_EXPIRE_MINUTES=15
PHONE_VERIFICATION_PHONE_DAILY_LIMIT=10
PHONE_VERIFICATION_IP_HOURLY_LIMIT=20
PHONE_VERIFICATION_TRUST_X_FORWARDED_FOR=True
TENCENT_SECRET_ID=secret-id
TENCENT_SECRET_KEY=secret-key
TENCENT_SDK_APPID=1400000000
TENCENT_SMS_SIGN_NAME=短信签名
TENCENT_SMS_TEMPLATE_ID=模板ID
ALIBABA_CLOUD_ACCESS_KEY_ID=access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=access-key-secret
ALIYUN_SMS_SIGN_NAME=短信签名
ALIYUN_SMS_TEMPLATE_CODE=SMS_123456789

OIDC_RSA_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n
短信服务商选择 腾讯云和阿里云可以只配置其中一家，也可以同时配置。只配置一家时系统自动选用；两家均配置完整时， 超级管理员可在 Django Admin 的“Accounts → 短信服务设置”中切换发送渠道。密钥只从环境变量读取， 不会保存到数据库。
issuer 必须稳定 SOVEREIGNID_ISSUER_URL 是 OIDC issuer，也是 discovery、JWKS、userinfo 等端点返回 URL 的根地址。 它必须和用户访问的公网地址、业务系统填写的自动发现 URL 保持同一个 origin。

开发环境可用下面的命令生成测试用 RSA 私钥，并把换行转义为 \n 后填入环境变量。

openssl genrsa 2048 | awk '{printf "%s\\n", $0}'

三、初始化数据库和管理员

首次启动前执行数据库迁移，并创建一个管理员账号，用于进入 Django Admin 或后续的应用管理页面。

conda run -n SovereignID python manage.py migrate
conda run -n SovereignID python manage.py createsuperuser

四、启动 Web 和 Celery

Web 进程负责登录、自动注册、授权和 OIDC 端点；Celery worker 负责异步发送验证邮件。 两个进程需要使用同一份环境变量。 

conda run -n SovereignID python manage.py runserver 0.0.0.0:8000
conda run -n SovereignID celery -A SovereignID worker -l info

容器化或生产部署时，也需要保持同样的进程边界：至少一个 Web 服务和一个 Celery worker， 并确保静态文件、数据库、Redis、邮件配置都已经就绪。

五、基础验收

  • 访问 SovereignID 首页和文档中心，页面可以正常打开。
  • 管理员可以登录后台，并能管理用户、用户组和 OIDC 应用。
  • 新邮箱或手机号可以收到登录验证码，请求验证码时数据库中尚未创建用户。
  • 验证码校验成功后自动创建账号并完成登录；手机号账号绑定验证邮箱后才允许继续 OIDC 授权。
  • 访问 <SOVEREIGNID_ISSUER_URL>/.well-known/openid-configuration 能看到 discovery JSON。
  • discovery JSON 中的 issuer 与 SOVEREIGNID_ISSUER_URL 完全一致。

六、下一步

快速开始完成后，再为具体业务系统创建 OIDC 应用。接入 Gitea 时，需要把 Gitea 回调地址登记到 SovereignID， 然后在 Gitea 管理后台添加 OpenID Connect 认证源。