跳转到正文

Web 安装流程 ​

通过二进制部署、Docker Compose 部署或 Kubernetes 部署启动 Sayrud 后,访问 http://服务器地址:2830/setup。未安装时,访问首页也会跳转到这里。

安装分为验证身份、数据库、管理员和完成四步。页面右上角可以切换语言。

验证身份 ​

未指定安装令牌时,程序会在启动日志里打印 Setup token: 和一个带令牌的安装链接。复制令牌到页面,点击“验证”。远程部署时,日志链接中的 localhost 需要换成实际访问地址。

部署方式查看日志
前台运行当前终端
systemdsudo journalctl -u sayrud -n 100 --no-pager
Docker Composedocker compose logs --tail=100 sayrud
Kuberneteskubectl -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:

yaml
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,将完整输出填入配置:

sh
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 是否变化。先找回原配置和数据,不要在新向导里覆盖原部署。