125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
# accounts.svc.plus
|
||
|
||
Cloud Neutral Toolkit 的账号与身份服务 (Account Service).
|
||
|
||
> A production-oriented account service for sign-in, sessions, MFA, and agent coordination.
|
||
|
||
## 部署要求 (Deployment Requirements)
|
||
|
||
| 维度 | 要求 / 规格 | 说明 |
|
||
|---|---|---|
|
||
| 网络 | 可访问的 API 域名 (可选) | 生产建议配置 `server.publicUrl` |
|
||
| 端口 | `:8080` | API 服务默认监听端口 |
|
||
| 数据库 | PostgreSQL | 存储账号/会话/状态等核心数据 |
|
||
| 缓存 (可选) | Redis | `session.cache=redis` 时需要 |
|
||
| 最低 | 1 CPU / 1GB RAM | 开发/小规模 |
|
||
| 推荐 | 2 CPU / 2GB RAM | 生产建议 |
|
||
|
||
## 快速开始 (Quickstart)
|
||
|
||
### 一键初始化 (Setup Script)
|
||
|
||
```bash
|
||
curl -fsSL "https://raw.githubusercontent.com/cloud-neutral-toolkit/accounts.svc.plus/main/scripts/setup.sh?$(date +%s)" \
|
||
| bash -s -- accounts.svc.plus --mode process --deploy
|
||
```
|
||
|
||
Docker 部署模式：
|
||
|
||
```bash
|
||
curl -fsSL "https://raw.githubusercontent.com/cloud-neutral-toolkit/accounts.svc.plus/main/scripts/setup.sh?$(date +%s)" \
|
||
| bash -s -- accounts.svc.plus --mode docker --deploy
|
||
```
|
||
|
||
Cloud Run 部署模式：
|
||
|
||
```bash
|
||
curl -fsSL "https://raw.githubusercontent.com/cloud-neutral-toolkit/accounts.svc.plus/main/scripts/setup.sh?$(date +%s)" \
|
||
| bash -s -- accounts.svc.plus --mode cloudrun
|
||
```
|
||
|
||
单机 `process` / `docker` 模式默认会写入 Caddy 站点配置到 `/etc/caddy/conf.d/accounts.svc.plus.conf`，并反向代理到本机 `127.0.0.1:8080`。
|
||
|
||
### 本地运行 (Local Dev)
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
make dev
|
||
```
|
||
|
||
## 提交前同步要求 (Pre-Commit Sync Requirement)
|
||
|
||
控制仓库中的 `subrepos/accounts.svc.plus` 在每次提交前，必须先同步当前线上运行实例。
|
||
|
||
线上实例命名规则：
|
||
|
||
- `<server-name>-<hostname-or-env>-<git-commit-short-id>.<domain>`
|
||
|
||
例如：
|
||
|
||
- `accounts-us-xhttp-2886a64.svc.plus`
|
||
|
||
执行要求：
|
||
|
||
```bash
|
||
cd /Users/shenlan/workspaces/cloud-neutral-toolkit/github-org-cloud-neutral-toolkit/subrepos/accounts.svc.plus
|
||
|
||
# 1. 确认线上当前运行 revision / image
|
||
ssh root@us-xhttp.svc.plus 'docker ps --format "table {{.Names}}\t{{.Image}}\t{{.RunningFor}}" | grep accounts'
|
||
|
||
# 2. 动态定位当前 active accounts 实例并核对 compose 目录与镜像 tag
|
||
ssh root@us-xhttp.svc.plus '
|
||
name=$(docker ps --format "{{.Names}}" | grep "^accounts-" | head -n 1) &&
|
||
echo "$name" &&
|
||
sed -n "1,80p" "/opt/cloud-neutral/accounts/${name}/docker-compose.yml"
|
||
'
|
||
|
||
# 3. 再开始本地提交
|
||
git status
|
||
```
|
||
|
||
如果线上 revision 已变化，应先以新的 `<server-name>-<hostname-or-env>-<git-commit-short-id>.<domain>` 实例为准完成同步，再提交本地改动。
|
||
|
||
## Stripe 配置 (Stripe Billing Setup)
|
||
|
||
Stripe 相关服务端能力现在由 `accounts.svc.plus` 承担，包括：
|
||
|
||
- Checkout Session 创建
|
||
- Customer Portal 跳转
|
||
- Webhook 验签与订阅状态回写
|
||
|
||
需要的环境变量：
|
||
|
||
| 变量 | 用途 |
|
||
| --- | --- |
|
||
| `STRIPE_SECRET_KEY` | Stripe API secret key |
|
||
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook endpoint secret |
|
||
| `STRIPE_ALLOWED_PRICE_IDS` | 允许下单的 `price_...` 白名单，逗号分隔 |
|
||
|
||
联调说明见 `docs/usage/stripe-billing.md`。
|
||
|
||
## 核心特性 & 技术栈 (Features & Tech Stack)
|
||
|
||
核心特性：
|
||
- 账号体系：注册/登录/会话/角色与权限
|
||
- 安全能力：邮件验证、TOTP MFA（可选）
|
||
- Agent 协同：与节点/控制面协作的同步与状态上报
|
||
- 多部署形态：本地/VM、Docker、Cloud Run（含 stunnel sidecar 示例）
|
||
|
||
技术栈：
|
||
- Go + Gin
|
||
- PostgreSQL (primary store)
|
||
- Redis (optional session cache)
|
||
- stunnel (optional secure DB connectivity; Cloud Run example included)
|
||
|
||
## 说明文档 (Docs)
|
||
|
||
- 文档入口：`docs/README.md`
|
||
- 快速开始：`docs/getting-started/quickstart.md`
|
||
- 配置说明：`docs/usage/config.md`
|
||
- Stripe 联调：`docs/usage/stripe-billing.md`
|
||
- 部署方式：`docs/usage/deployment.md`
|
||
- API 参考：`docs/api/overview.md`
|
||
- 运维：`docs/operations/monitoring.md`, `docs/operations/troubleshooting.md`
|
||
- Runbooks：`docs/Runbook/README.md`
|