Web 安装流程
通过二进制部署、Docker Compose 部署或 Kubernetes 部署启动 Sayrud 后,访问 http://服务器地址:2830/setup。未安装时,访问首页也会跳转到这里。
安装分为验证身份、数据库、管理员和完成四步。页面右上角可以切换语言。
验证身份
未指定安装令牌时,程序会在启动日志里打印 Setup token: 和一个带令牌的安装链接。复制令牌到页面,点击“验证”。远程部署时,日志链接中的 localhost 需要换成实际访问地址。
| 部署方式 | 查看日志 |
|---|---|
| 前台运行 | 当前终端 |
| systemd | sudo journalctl -u sayrud -n 100 --no-pager |
| Docker Compose | docker compose logs --tail=100 sayrud |
| Kubernetes | kubectl -n sayrud logs deployment/sayrud --tail=100 |
如果设置了 SAYRUD_SETUP_TOKEN,直接填写该环境变量的值。K8s 示例使用的就是这种方式,令牌保存在创建 Secret 时的本地文件中。
自定义令牌在去除空格和连字符后至少需要 16 个字符,可以用 openssl rand -hex 24 生成。令牌验证忽略大小写、空格和连字符。
未固定令牌时,安装期间重启进程会生成新令牌,需要从最新日志重新获取。令牌及带令牌的链接应只交给负责安装的人;创建管理员后,安装接口会关闭。
配置数据库
新安装时填写以下信息:
| 服务 | 字段 |
|---|---|
| PostgreSQL | 主机、端口、数据库名、用户名、密码、SSL 模式 |
| Redis | 主机:端口 格式的地址,以及可选的用户名和密码 |
地址由运行 Sayrud 的进程访问,与浏览器所在的电脑无关。Docker Compose 示例使用 postgres 和 redis:6379;K8s 使用集群内 Service 名或可访问的外部域名。
PostgreSQL 的 SSL 模式包括“不加密”“加密连接”“加密并验证 CA 证书”“加密并验证证书和主机名”。按数据库服务要求选择,使用证书校验时也需要让运行环境信任相应 CA。
点击“测试连接”,确认 PostgreSQL 和 Redis 都显示连接成功,再点击“保存并继续”。
创建管理员
填写邮箱、用户名、密码和确认密码,再点击“完成安装”。
这里创建的是首个系统管理员,创建成功后会自动登录,点击“开始使用”进入应用。
安装完成后,确认可以创建项目、编辑记录和上传附件,再按部署方式检查配置和上传文件是否已持久化。站点设置、注册开关、登录方式和 AI 模型等可以在管理后台调整。
预先提供配置
需要由配置管理系统提供连接信息时,可以提前准备 sayrud.yaml。下面是本地存储的配置示例,先替换连接密码和 auth.secret_key:
postgres:
dsn: "postgres://sayrud:[email protected]:5432/sayrud?sslmode=disable"
redis:
address: "127.0.0.1:6379"
username: ""
password: ""
auth:
secret_key: "REPLACE_WITH_BASE64_KEY"
storage:
type: local
local:
path: ./data/storage用下面的命令生成 auth.secret_key,将完整输出填入配置:
openssl rand -base64 32手工编写 PostgreSQL URL 时,密码中的 @、:、/ 等特殊字符需要做 URL 编码。通过向导填写时,程序会处理编码。
将文件放到启动参数指定的位置,更完整的选项见项目示例配置。配置变更后需要重启程序。
常见问题
打开后没有安装页
如果日志显示已正常启动,且数据库已有用户,程序会直接提供应用页面,使用已有账号登录即可。
安装令牌失效
检查安装过程中是否重启了进程。未设置 SAYRUD_SETUP_TOKEN 时,使用最新日志里的令牌。K8s 先确认访问的 Pod 使用了预期 Secret,并保持首次安装为单副本。连续输错令牌会触发限流,应核对令牌后再试。
数据库测试失败
检查数据库是否已经创建、账号密码是否正确,以及应用所在主机或 Pod 能否访问目标地址。容器中的 127.0.0.1 指向容器自身。若连接成功但保存失败,还需要检查数据库账号是否有结构迁移权限。
新安装向导会拒绝接管已有用户的数据库。恢复已有实例时应还原原配置、密钥和上传文件,按正常启动流程连接原数据库,不要重新走数据库配置步骤。
保存配置时出现权限错误
向导会先在配置目录写临时文件,再提交为 sayrud.yaml,因此目录本身必须可写。检查是不是只读文件挂载、ConfigMap、Secret,或 UID/GID 与卷的所有者不匹配。Docker 和 K8s 镜像使用 10001:10001。
提示配置已保存,但需要重启
检查服务日志,排除后续服务初始化失败的原因,再用同一配置路径重启。已经写入的配置会被重新读取,无需删除文件重新安装。
重建容器后又出现安装页
检查配置目录是否挂载到 /home/app/config、是否仍使用原来的 PostgreSQL 数据库,以及 Compose 项目名或 K8s PVC 是否变化。先找回原配置和数据,不要在新向导里覆盖原部署。