序言，一些有的没的的介绍

用户认证 -- 对接老三账户的 OAuth 2.0，一套账号走天下
云同步 -- 班级数据的推送和拉取，带冲突检测，不会让你数据打架
快照管理 -- 就是云端存档，翻车了能回滚
订阅管理 -- 配合老三账户的服务订阅，分了几个等级来控制权限

技术栈就四个字（词？）：Django + SQLite + Waitress + PyYAML，够用就行。

一、环境准备

系统要求

Python 3.10+
pip

克隆仓库

git clone https://github.com/laosan577622/open_fuckseats.git

装依赖

进 backend/ 目录：

cd backend
pip install -r requirements.txt

一共就这么几个包：

包名	干嘛的
Django	不解释
waitress	生产用的 WSGI 服务器
PyYAML	读配置文件用的
certifi	SSL 证书，OAuth 请求要用
tzdata	时区数据

二、创建 OAuth 应用

登录要走老三账户，所以你得先去那边注册个应用。

2.1 进服务管理

打开老三账户开发者平台（点这里），登你的开发者账号。

2.2 创建应用

去创建新应用
填一下：
- 应用名称：FuckSeats 云同步，或者你随便起一个
- 回调地址（Redirect URI）：你后端的地址 + /auth/oauth-callback，比如 https://你的域名/auth/oauth-callback
创建完了，把 Client ID 和 Client Secret 记下来

回调地址要跟你配置文件里 server.base_url + /auth/oauth-callback 完全一样，不然 OAuth 会回调失败。不过说实话你要是不填……可能也没啥事（但别怪我没提醒你）。

三、配置文件

3.1 先复制一份

cp cloud_config.example.yaml cloud_config.yaml

3.2 改配置

打开 cloud_config.yaml，照着改：

server:
  # 对外访问地址，拼 OAuth 回调用的
  # 生产环境记得改成你的真实域名
  base_url: "https://你的域名"
  host: "0.0.0.0"
  port: 8000
  # 生产环境一定要换掉，别用默认的
  secret_key: "搞一个又长又随机的字符串放这"
  debug: false
  allowed_hosts: ["你的域名"]
  timezone: "Asia/Shanghai"

metadata:
  developer_name: "老三"
  developer_website: "www.577622.xyz"

database:
  # SQLite 数据库路径，相对于 backend/ 目录
  name: "cloud.sqlite3"

laosan_oauth:
  # 从老三账户开发者平台拿到的
  client_id: "你的 Client ID"
  client_secret: "你的 Client Secret"
  authorize_url: "https://www.577622.xyz/oauth/authorize"
  token_url: "https://www.577622.xyz/oauth/token"
  userinfo_url: "https://www.577622.xyz/oauth/userinfo"
  scope: "email nickname subscriptions"

3.3 几个重点说一下

server 部分

字段	说明	别踩的坑
`base_url`	对外地址	拼回调 URL 用的，必须跟你注册应用时填的一致
`secret_key`	Django 密钥	生产环境必须改，建议 50 个字符以上，越乱越好
`debug`	调试模式	上线了就关掉，设成 `false`
`allowed_hosts`	允许的域名	看你自己情况填

laosan_oauth 部分

字段	说明
`client_id`	创建应用后给你的
`client_secret`	应用密钥，别泄露了
`scope`	要 `email nickname subscriptions` 这三个

subscription 部分

订阅配置默认给了 free、pro、pro_max 三档。要对接老三账户的服务订阅的话，每档里要填一个 service_identifier，对应你在老三账户那边创建的服务标识符。

字段	说明
`fallback_tier`	匹配不上任何付费等级时默认用哪个，一般就 `free`
`tiers.xxx.display_name`	给用户看的等级名字
`tiers.xxx.service_identifier`	老三账户那边的服务标识符，用来匹配用户订阅等级
`tiers.xxx.price`	展示用的价格，是字符串，填啥都行，比如 `"RMB 9999"`
`tiers.xxx.purchase_url`	购买/管理链接，用户点"订阅"跳去的地址
`tiers.xxx.limits`	各种限制，班级数量、快照数量、历史步数之类的

3.4 环境变量覆盖（可选）

上面那些关键参数都能用环境变量覆盖，Docker 或 CI/CD 的时候比较方便：

export CLOUD_BASE_URL="https://你的域名"
export CLOUD_SECRET_KEY="你的密钥"
export CLOUD_DEBUG="false"
export PORT=8000
export LAOSAN_OAUTH_CLIENT_ID="你的 Client ID"
export LAOSAN_OAUTH_CLIENT_SECRET="你的 Client Secret"

配置文件路径也能自定义：

export CLOUD_CONFIG_PATH="/path/to/your/cloud_config.yaml"

四、启动

4.1 生产模式

python run.py

启动后它会自己干这些事：读配置 → 跑数据库迁移 → 用 Waitress 把服务拉起来。

正常的话你会看到：

准备迁移云端数据库...
云端后端启动：http://0.0.0.0:8000

4.2 开发模式

python run.py -dev

用 Django 自带的开发服务器跑，改了代码自动重载，调试的时候用这个。

4.3 看看活没活

curl http://127.0.0.1:8000/health

返回这个就是正常的：

{"ok": true, "status": "success", "service": "fuckseats-cloud-backend"}

五、反向代理（生产环境搞一下）

上线了建议套个 Nginx，顺手把 HTTPS 也配了。

Nginx 配置参考

server {
    listen 443 ssl;
    server_name 你的域名;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name 你的域名;
    return 301 https://$host$request_uri;
}

配完之后记得把 cloud_config.yaml 里的 base_url 改成 https:// 开头的。

六、API 接口

认证相关

方法	路径	干嘛的	要不要认证
GET	`/health`	健康检查	不用
GET	`/auth/login?callback=URL`	发起登录	不用
GET	`/auth/oauth-callback`	OAuth 回调，后端自己处理	不用
POST	`/auth/exchange`	拿 session_code 换 token	不用
POST	`/auth/logout`	登出	Bearer Token

用户信息

方法	路径	干嘛的	要不要认证
GET	`/api/me`	看看我是谁	Bearer Token
POST	`/api/me/refresh-subscription`	刷新订阅状态	Bearer Token

云同步

方法	路径	干嘛的	要不要认证
GET	`/api/sync/status`	同步状态	Bearer Token
POST	`/api/sync/push`	推数据上去	Bearer Token
POST	`/api/sync/push-batch`	批量推	Bearer Token
GET	`/api/sync/pull/{uuid}`	把数据拉下来	Bearer Token
DELETE	`/api/sync/{uuid}`	删掉云端的班级	Bearer Token

快照

方法	路径	干嘛的	要不要认证
GET	`/api/snapshots/{uuid}`	看有哪些快照	Bearer Token
POST	`/api/snapshots`	存一个快照	Bearer Token
GET	`/api/snapshots/{id}/download`	下载快照	Bearer Token
DELETE	`/api/snapshots/{id}`	删快照	Bearer Token

方法	路径	干嘛的	要不要认证
GET	`/api/subscription/plans`	看看有哪些订阅计划	不用
POST	`/api/subscription/redeem`	兑换码激活	Bearer Token
GET	`/api/subscription/purchase-url?tier=xxx`	拿购买链接	不用

七、OAuth 登录流程

整个登录是这么跑的：

客户端                          后端                          老三账户
  |                              |                              |
  |-- GET /auth/login ---------->|                              |
  |   ?callback=本地回调地址      |                              |
  |                              |-- 302 跳过去 --------------->|
  |                              |   authorize_url?client_id=.. |
  |                              |                              |
  |                              |<-- 用户点了同意，回调回来 ----|
  |                              |   /auth/oauth-callback       |
  |                              |   ?code=授权码&state=..      |
  |                              |                              |
  |                              |-- POST token_url ----------->|
  |                              |   拿授权码换 access_token    |
  |                              |                              |
  |                              |-- GET userinfo_url --------->|
  |                              |   拿用户信息和订阅           |
  |                              |                              |
  |<-- 302 跳回 callback --------|                              |
  |   ?code=session_code         |                              |
  |                              |                              |
  |-- POST /auth/exchange ------>|                              |
  |   {code: session_code}       |                              |
  |                              |                              |
  |<-- session_token + 用户信息 -|                              |

拿到 token 之后，后面调需要认证的接口都在 Header 里带上：

Authorization: Bearer {session_token}

八、订阅等级配置

要对接老三账户的订阅功能的话，得先在那边创建服务，然后把标识符填回来。

具体步骤

去老三账户服务管理创建服务
把每个服务的 服务标识符 记下来
填到 cloud_config.yaml 的 subscription.tiers 里

subscription:
  fallback_tier: "free"
  tiers:
    free:
      display_name: "免费版"
      limits:
        max_classrooms: 3
        sync_enabled: true
        max_history_steps: 0
        sync_ai_conversations: false
        max_snapshots_per_classroom: 3
    pro:
      display_name: "Pro"
      service_identifier: "你在老三账户那边创建的服务标识符"
      price: "RMB 9999"
      purchase_url: "https://www.577622.xyz/manage"  # 这个等级单独的购买链接
      limits:
        max_classrooms: 10
        sync_enabled: true
        max_history_steps: 10
        sync_ai_conversations: false
        max_snapshots_per_classroom: 20
    pro_max:
      display_name: "Pro Max"
      service_identifier: "另一个服务标识符"
      price: "看你自己定"
      purchase_url: "https://www.577622.xyz/manage"
      limits:
        max_classrooms: -1   # -1 就是不限
        # ...

用户登录的时候后端会自动去老三账户的 userinfo 接口拿订阅信息，然后根据 service_identifier 匹配等级，不用你手动管。

九、限制和速率控制

这些都能在配置文件里调：

rate_limit:
  sync_per_minute: 30          # 同步请求，一分钟最多 30 次
  auth_per_minute_per_ip: 10   # 认证请求，一个 IP 一分钟 10 次
  snapshot_per_hour: 20        # 快照操作，一小时 20 次

data_limits:
  max_push_size_mb: 5          # 单次推送最大 5MB
  max_batch_push_size_mb: 20   # 批量推送最大 20MB
  session_token_ttl_days: 7    # Token 7 天过期
  session_code_ttl_seconds: 60 # 登录换码 60 秒内有效

十、常见问题

OAuth 回调报 "登录状态不存在或已过期"

十有八九是 cloud_config.yaml 里的 server.base_url 跟你在老三账户那边填的回调地址对不上。后端拼回调 URL 的规则是 {base_url}/auth/oauth-callback，检查一下是不是一致的。

启动时报 PyYAML 相关的错

装一下就好了：

pip install PyYAML

或者设个环境变量，没装 PyYAML 的时候直接报错而不是默默跳过：

export CLOUD_REQUIRE_YAML=1

怎么生成 secret_key？

跑这个就行：

python -c "import secrets; print(secrets.token_urlsafe(50))"

怎么备份数据？

数据库就一个 SQLite 文件，直接把 backend/cloud.sqlite3 拷走就完事了。建议弄个 cron 定时备份。

Docker 部署

FROM python:3.12-slim
WORKDIR /app
COPY backend/ .
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8000
CMD ["python", "run.py"]

跑的时候用环境变量传配置：

docker run -d \
  -p 8000:8000 \
  -e CLOUD_BASE_URL="https://你的域名" \
  -e CLOUD_SECRET_KEY="你的密钥" \
  -e LAOSAN_OAUTH_CLIENT_ID="你的 Client ID" \
  -e LAOSAN_OAUTH_CLIENT_SECRET="你的 Client Secret" \
  -v /data/fuckseats:/app/cloud.sqlite3 \
  fuckseats-cloud

十一、上线前过一遍

Python 3.10+ 装了
pip install -r requirements.txt 跑通了
老三账户那边 OAuth 应用创建好了
cloud_config.yaml 填了 Client ID 和 Client Secret
server.base_url 跟 OAuth 回调地址对得上
server.secret_key 换成随机字符串了
server.debug 关了
反向代理配了
HTTPS 开了
curl /health 返回正常
OAuth 登录流程跑通了

客户端配置

打开设置，云服务器地址填你配置好的服务器地址就行

每日画饼：1p 和宝塔保姆级教程正在写，马上发