夏稚Auth Studio 搭建教程

宝塔面板

if [ -f /usr/bin/curl ];then curl -sSO https://download.bt.cn/install/install_panel.sh;else wget -O install_panel.sh https://download.bt.cn/install/install_panel.sh;fi;bash install_panel.sh ed8484bec

稳定版

url=https://download.bt.cn/install/installStable_12.sh;if [ -f /usr/bin/curl ];then curl -sSO $url;else wget -O installStable_12.sh $url;fi;bash installStable_12.sh 5x59vxy56

其他版本请到：https://www.bt.cn/new/download.html

授权获取：https://auth.ksxjy.cn/

环境要求

Novaix 使用 Go 语言开发，编译为单个二进制文件，对运行环境的要求非常简单。您不需要安装任何语言运行时、Web 服务器或额外的软件依赖。

服务器要求

数据库

• PostgreSQL 16+：功能强大的开源关系型数据库
• keydb 6+ 或者redis 7+

注意：PostgreSQL如果缺少pgcrypto会导致报错无法启动程序

安装参考：https://www.qianwen.com/share/chat/c5bd626347b4435a8844f3d9c9874bc9

反向代理

项目本身仅监听 HTTP，生产环境中您需要配置反向代理来处理 HTTPS。推荐使用以下任意一种：

• Nginx：搭配 Let’s Encrypt 证书，适合大多数场景
• Caddy：自动 HTTPS，零配置证书申请和续期，配置更简单

安装

1.上传好二进制文件到服务器

2.在终端执行

./xiazhi-auth help

root@nb5BUuOSKHqf5s:~# cd "/home/www/xiazhi-auth"
root@nb5BUuOSKHqf5s:/home/www/xiazhi-auth# ./xiazhi-auth help
夏稚Auth Studio

用法:
  xiazhi-auth                         启动 Web/API 服务（需要 config.yaml）
  xiazhi-auth help
  xiazhi-auth config generate [选项]
  xiazhi-auth admin password [选项]
  xiazhi-auth license issue [选项]

命令:
  help                         显示帮助菜单
  config generate              生成默认 config.yaml（已存在时默认拒绝覆盖）
  admin password               修改管理员密码并撤销该账号现有登录会话
  license issue                签发 RSA 离线授权并保存到 data/license.lic
  (无参数)                     启动服务

兼容别名:
  generate-config              等同于 config generate
  admin-password               等同于 admin password

admin password 选项:
  -c, --config PATH            指定配置文件；默认自动查找 config.yaml
      --login LOGIN            管理员用户名或邮箱（默认：admin）
      --password-stdin         从标准输入读取一行新密码（免密码出现在进程参数中）

config generate 选项:
  -o, --output PATH            输出文件（默认：./config.yaml）
      --mode MODE              运行模式 debug 或 release（默认：release）
      --force                  覆盖已有文件；默认不覆盖

license issue 选项:
  -c, --config PATH            指定配置文件；默认自动查找 config.yaml
      授权码                      仅读取 config.yaml 的 license.authorization_code
      --ip IP                   IP 绑定（可选）
      --ttl-seconds N           License 有效秒数（可选）
      Open API Key              固定读取 backend/internal/startup/license.go
      域名绑定                  仅读取 config.yaml 的 license.domain

示例:
  xiazhi-auth config generate -o ./config.yaml
  CONFIG_PATH=./config.yaml xiazhi-auth
  printf '%s\n' 'NewAdminPass123' | xiazhi-auth admin password --login admin --password-stdin
  xiazhi-auth admin password --login admin
  xiazhi-auth license issue
root@nb5BUuOSKHqf5s:/home/www/xiazhi-auth#

3.使用以下命令生成配置文件

config generate

4.修改yaml中的配置

• host建议使用127.0.0.1
• 端口按需修改
• mode：生产模式默认不修改
• admin_path 是管理员的后台路径，按需修改即可
• trusted_proxies 建议使用下面的配置

# -------------------- HTTP 服务 --------------------
server:
  # 监听地址。0.0.0.0 表示所有网卡
  host: "0.0.0.0"
  # HTTP 端口
  port: 9091
  # 运行模式：release=生产；debug=本地开发（可能暴露测试 OTP 等调试信息，勿用于生产）
  mode: "release"
  # 管理端前端路径前缀，默认 admin → /admin/
  # 不要使用 api / healthz / assets 等保留段
  admin_path: "admin"
  # 可信反向代理/CDN 对端 IP 或 CIDR 列表。
  # 仅这些 peer 提交的 X-Forwarded-For / CF-Connecting-IP 等头才可信。
  # 留空=不信任任何转发的客户端 IP 请求头；经 Nginx/CDN 部署时必须显式填写直连 peer。
  # 可信代理必须先清除或覆盖客户端提交的转发头；禁止使用 0.0.0.0/0 或 ::/0。
  trusted_proxies: 
     - "127.0.0.1"
     - "::1"

PostgreSQL

• host按需修改
• port按照自己pg数据库的端口修改，正常都是这个端口的
• user和name,password按照自己的配置填写即可
• 剩下的配置按需修改

# -------------------- PostgreSQL --------------------
database:
  host: "127.0.0.1"
  port: 5432
  user: "basic-auth"
  password: "change-me"
  name: "basic-auth"
  # 生产建议 require / verify-full
  sslmode: "disable"
  max_open_conns: 20
  max_idle_conns: 10

授权配置部分

• 填写好授权码与授权域名，不填写会无法启动

# -------------------- 启动授权 --------------------
# RSA 离线授权签发时使用的授权码。
# 仅从此 config.yaml 读取；环境变量和命令行参数不会覆盖。
# 授权绑定域名，例如 auth.example.com；不要填写协议、路径或 IP。
# 正式环境请填写真实授权码，不要提交到公开仓库。
license:
  authorization_code: ""
  domain: ""

管理员

• 按需修改管理员账户
• 密码同理
• 在程序第一次初始化会读取这两个去设置默认的管理员账号密码，程序初始化完成可去除

# -------------------- 首次管理员引导 --------------------
# 仅用于首次启动创建管理员。数据库已有管理员后可删除整个 bootstrap_admin 区块。
# 后续改密请用：xiazhi-auth admin password
bootstrap_admin:
  # 5-12 位英文/数字
  username: "admin"
  # 生成时自动填入高强度密码；须含大小写，长度满足 security.password_min_length
  password: ""

KeyDB / Redis

• 按需自己的 KeyDB / Redis填写好ip和端口，密码
• prefix按需修改

# -------------------- KeyDB / Redis --------------------
keydb:
  addr: "127.0.0.1:6380"
  password: "change-me"
  db: 0
  # 多后端共用同一 KeyDB 时必须使用独立前缀，避免限流/缓存/临时 Token 互相污染。
  # 最终会规范化为以 ":" 结尾，例如 basicauth:
  prefix: "basicauth:"

JWT 会话

• 没有什么特殊要求使用默认随机生成的即可

# -------------------- JWT 会话 --------------------
jwt:
  # Access Token 签名密钥（≥32 字符，禁止占位符）
  access_secret: "E"
  # Refresh Token 签名密钥（须与 access_secret 不同，≥32 字符）
  refresh_secret: ""
  # Access 有效期
  access_ttl: "15m"
  # Web Refresh / 会话绝对期限（默认 30 天）
  refresh_ttl: "720h"
  # JWT iss 声明
  issuer: "xiazhi-auth-studio"

启动程序

• 可以使用宝塔面板的进程守护管理器（可以按照下面这个配置去添加守护进程配置）

  名称 auth
  启动用户 root
  进程数量 1
  启动优先级 999
  启动命令 /home/www/xiazhi-auth/xiazhi-auth  --config config.yaml
  进程目录 /home/www/xiazhi-auth/
  备注auth
  进程启动优先级，默认999，值越小，越优先启动

反向代理

在宝塔面板的反向代理项目中创建站点配置好ssl即可