早风依旧的博客
项目部署

夏稚Auth Studio 部署实践记录

2026-07-29 #授权系统
早风依旧
正在加载歌曲信息……
私有音源
0:00 0:00
正在加载歌曲信息……

xiazhi-auth-1

xiazhi-auth-2

xiazhi-auth-3

已完成的部署步骤

1. 环境准备

  • 主机商：RackNerd
  • 系统：Linux amd64
  • 面板：1Panel
  • 工作目录：/home/xiazhiauth

2. 安装前端依赖

1
2
cd /home/xiazhiauth/yuanma/xiazhi-auth-studio/frontend
pnpm install --frozen-lockfile

说明：

  • pnpm — Node.js 包管理器
  • install — 安装依赖
  • --frozen-lockfile — 按 pnpm-lock.yaml 锁定版本安装，不更新锁文件
  • 结果：552 个依赖安装成功

3. 构建二进制

授权版（交付客户用）

1
2
cd /home/xiazhiauth/yuanma/xiazhi-auth-studio
make build
步骤 命令 说明
前端构建 tsc -b && vite build TypeScript 类型检查 + Vite 打包，产出 frontend/dist
嵌入前端 cp -a frontend/dist -> backend/internal/web/dist 把前端文件嵌入 Go 代码
编译后端 CGO_ENABLED=0 go build -ldflags="-s -w" 编译为静态二进制，产出 release/xiazhi-auth

无授权版（自用）

1
make build-noauth

产物：release/xiazhi-auth-noauth，37MB 单二进制。

授权版 无授权版
启动授权检查 ✅ 需要授权码 + 域名 ❌ 跳过
用途 交付给客户 自己开发/测试/自用
业务功能 完全一致 完全一致

4. 部署二进制

1
2
cp /home/xiazhiauth/yuanma/xiazhi-auth-studio/release/xiazhi-auth-noauth /home/xiazhiauth/
mkdir -p /home/xiazhiauth/version-files

最终目录结构：

1
2
3
4
5
/home/xiazhiauth/
├── xiazhi-auth-noauth       # 无授权版二进制
├── config.yaml              # 配置文件
├── version-files/           # 版本文件存储（按需使用）
└── yuanma/                  # 源码目录

5. 生成配置

1
2
cd /home/xiazhiauth
./xiazhi-auth-noauth config generate -o config.yaml

生成结果：

  • 配置文件：/home/xiazhiauth/config.yaml
  • 管理员账号：admin
  • 管理员密码：Ar35ErvmoLe2YfXzwzc5b2cA（仅显示一次，已保存）
  • 所有密钥均为自动生成的随机值

6. 修改配置

根据 1Panel 环境修改以下关键项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# PostgreSQL — 1Panel 创建数据库后填写
database:
  host: "127.0.0.1"          # Docker 容器需改为网关 IP
  port: 5432
  user: "xiazhi-auth-noauth"
  password: "3xHZYr4QHC4GXjGh"
  name: "xiazhi-auth-noauth"

# 授权相关（无授权版留空）
license:
  authorization_code: ""
  domain: ""

# Redis — 注意默认生成端口是 6380，1Panel 一般是 6379
keydb:
  addr: "127.0.0.1:6379"
  password: "redis_F3cfmD"
  db: 10
  prefix: "basicauth:"

# 首次管理员（初始化后需删除此段）
bootstrap_admin:
  username: "admin"
  password: "Ar35ErvmoLe2YfXzwzc5b2cA"

查看 Redis 数据库占用情况

在为项目选择 Redis 数据库编号前，建议先检查当前已经有哪些 DB 存在数据，避免和其他项目使用同一个 DB。

执行下面的命令进入 Redis：

1
docker exec -it 1Panel-redis-AzYr redis-cli -a 'redis_F3cfmD'

其中1Panel-redis-AzYr为我部署的redis容器名称。redis_F3cfmD为redis密码。

进入 Redis 命令行后执行：

1
INFO keyspace

返回结果类似：

1
2
3
4
5
6
7
8
9
# Keyspace
db0:keys=2,expires=0,avg_ttl=0,subexpiry=0
db1:keys=6152,expires=1,avg_ttl=26493786832,subexpiry=0
db2:keys=21980,expires=0,avg_ttl=0,subexpiry=0
db3:keys=2,expires=2,avg_ttl=979208,subexpiry=0
db5:keys=1513,expires=1,avg_ttl=13429507983,subexpiry=0
db6:keys=39,expires=5,avg_ttl=243734539,subexpiry=0
db13:keys=56,expires=30,avg_ttl=1359153476,subexpiry=0
db14:keys=4,expires=4,avg_ttl=553734727,subexpiry=0

出现在结果中的 DB 表示当前已经存在 Key。

根据上面的结果，已经存在数据的数据库有：

1
2
3
4
5
6
7
8
db0
db1
db2
db3
db5
db6
db13
db14

没有出现在结果中的 DB 当前为空：

1
2
3
4
5
6
7
8
db4
db7
db8
db9
db10
db11
db12
db15

因此，本次为夏稚 Auth Studio 选择 db10：

1
2
3
4
5
keydb:
  addr: "127.0.0.1:6379"
  password: "redis_F3cfmD"
  db: 10
  prefix: "basicauth:"

还可以在 Redis 命令行中执行下面的命令，确认 Redis 一共配置了多少个逻辑数据库：

1
CONFIG GET databases

默认一般会返回：

1
2
1 "databases"
2 "16"

这表示 Redis 当前共有 16 个逻辑数据库，可以使用的编号为 db0 至 db15。

项目停止运行后，只会断开与 Redis 的连接，不会自动清空项目写入的数据。

没有设置过期时间的 Key 会一直保留；设置了 TTL 的 Key 才会在到期后自动删除。因此，即使某个项目已经停止，也不能仅凭项目状态判断对应的 Redis DB 已经可以重新使用。

Redis 的不同 DB 只是逻辑分区，并不具备真正的权限隔离。除了给不同项目选择不同的 DB，还建议设置独立的 Key 前缀。本项目使用的前缀为 basicauth:，可以减少与其他项目的 Key 发生冲突。

7. 前台启动验证

1
CONFIG_PATH=/home/xiazhiauth/config.yaml /home/xiazhiauth/xiazhi-auth-noauth

成功日志：

1
2
3
4
PostgreSQL  ✅ 已连接
KeyDB       ✅ 已连接
数据表      ✅ 29/29 正常（迁移 6 条）
服务监听    ✅ http://[::]:9091

验证：

1
2
curl -fsS http://127.0.0.1:9091/healthz
# 返回: {"status":"ok"}

确认后 Ctrl+C 停止。

8. 配置 1Panel 进程守护

1Panel 面板 → 面板设置 → 进程守护，创建守护进程：

字段 值
名称 auth-xiazhi
启动用户 root
运行目录 /home/xiazhiauth
启动命令 /home/xiazhiauth/xiazhi-auth-noauth
进程数量 1
环境变量 CONFIG_PATH=/home/xiazhiauth/config.yaml
自动重启 开启
自动启动 开启
停止信号 TERM
停止等待 20 秒

9. 配置 1Panel 反向代理 + HTTPS

1Panel 面板 → 网站 → 创建网站 → 反向代理：

字段 值
域名 用户自己的域名（如 auth.example.com）
代理地址 http://127.0.0.1:9091
HTTPS 勾选，自动申请 Let’s Encrypt 证书

创建完成后，在网站 设置 → 配置文件 的 server 块中可根据需要添加：

1
client_max_body_size 2048m;

这个配置的作用：系统支持上传软件安装包/更新包（如 .exe、.zip 等），默认最大允许 2048MB。但 Nginx 默认限制上传只有 1MB，不加这行的话上传大文件会被 Nginx 拦截。

如果你用不到上传安装包的功能，可以不配这行，不影响正常使用。

10. 访问入口

入口 地址
用户前端 https://域名/
管理后台 https://域名/admin/login

默认管理员账号：

  • 用户名：admin
  • 密码：Ar35ErvmoLe2YfXzwzc5b2cA

后续建议

  • 绑定 TOTP 二因素认证，保存恢复码
  • 从 config.yaml 中删除 bootstrap_admin 整个配置段
  • 删除后重启进程守护
  • 配置 CORS（如有跨域需求）
  • 配置站点信息、邮件、支付等业务设置

附录：常用管理操作

修改管理员密码

方式一：CLI 命令（忘记密码登不进去时用）

1
2
cd /home/xiazhiauth
CONFIG_PATH=/home/xiazhiauth/config.yaml ./xiazhi-auth-noauth admin password --login admin

按提示输入新密码即可，会自动撤销该账号的所有现有登录会话。

一行搞定（不交互）：

1
printf '%s\n' '新密码' | CONFIG_PATH=/home/xiazhiauth/config.yaml ./xiazhi-auth-noauth admin password --login admin --password-stdin

方式二：后台网页（已登录时用）

登录后台 → 右上角头像 → 修改密码 → 输入旧密码和新密码 → 保存

修改管理员用户名

CLI 没有改用户名的命令，需在后台网页操作：

  1. 登录后台 → 左侧菜单 管理员
  2. 找到要改的账号，点击编辑
  3. 修改用户名 → 保存

如果改的是首次引导管理员（bootstrap_admin），改完后建议去 config.yaml 中删除整个 bootstrap_admin 配置段，然后重启进程守护，此后账号信息完全以数据库为准。

评论
分享

相关文章

查看更多
GMPay Edge 部署实践记录：使用 Cloudflare Workers 搭建加密货币支付网关 2026-07-30
GMShop Edge 部署实践记录：使用 Cloudflare Workers 搭建数字商品商城 2026-07-30

评论