首次安装

安装前必须知道：安装向导只初始化存储和管理员，不会自动创建公开短域名或配置 DNS、证书、反向代理。创建正式短链前，应用收到的 HTTP Host 必须与后台域名记录完全一致，否则后台和健康检查正常，公开短链仍可能返回 404。

服务第一次启动且不存在安装锁时，访问根地址会自动进入安装向导。安装向导依次完成许可确认、存储配置、管理员创建和安装确认。

1. 阅读并接受许可协议

打开 http://<服务器地址>:<端口>/，阅读软件许可协议，勾选“我已仔细阅读并同意上述许可协议”，然后选择“下一步”。不同意协议时不要继续安装。

2. 配置数据库、缓存与发号器

安装向导支持两类常用组合：

场景	数据库	缓存驱动	发号器驱动
本地体验或单机部署	SQLite	内存缓存	本地发号器
正式环境或多实例部署	MySQL/PostgreSQL	Redis	Redis

选择 SQLite 时填写一个持久化文件路径，例如 ./config/sqlite.db。选择 MySQL 或 PostgreSQL 时填写主机、端口、数据库名、用户名和密码。

缓存驱动与发号器驱动可以分别选择。只要其中一项使用 Redis，就必须填写 Redis 主机、端口、密码和数据库索引。填写完成后选择“测试连接”；测试成功后才能进入下一步。

3. 创建系统管理员

填写管理员用户名和两次相同的密码，邮箱为可选项。密码不得少于 6 位；正式环境应使用无法猜测且未在其他系统复用的密码。

4. 确认并开始安装

核对数据库、Redis、缓存、发号器和管理员摘要，然后选择“开始安装”。系统会写入配置、执行数据库迁移、创建管理员和安装锁，并在完成后跳转到登录页。

安装完成后应持续保留以下内容：

• config/config.yaml：当前运行配置。
• config/install.lock：安装完成标记，不应随意删除。
• SQLite 数据文件或外部数据库。
• data 与 logs 目录；品牌 Logo 等上传文件保存在数据目录中。

安装完成后的首次使用说明

通过服务器 IP 或管理域名完成安装，只代表后台和存储已经可用，不会自动创建公开短域名，也不会自动配置 DNS、证书或反向代理。创建第一条正式短链前必须完成以下工作：

1. 为公开短域名配置 DNS 和 HTTPS 证书。
2. 将公开域名反向代理到应用端口，并保留原始 HTTP Host。
3. 在后台“链接管理 → 域名”中填写与应用实际收到的 Host 完全一致的域名；非标准端口也要包含在内。
4. 创建测试短链，并分别从应用上游和公开 HTTPS 入口执行一次真实 GET 验证。

服务以 Host + 短码 精确查找记录，因此 /health 正常或后台可以登录，并不能证明公开短链域名已经配置正确。继续阅读创建首个域名与短链接；使用宝塔时参阅宝塔面板安装教程。

常见问题

• “下一步”不可用：先执行数据库连接测试，并根据提示修正连接参数。
• SQLite 安装失败：确认配置目录存在且运行用户拥有写权限。
• 容器连接外部数据库失败：容器内的 localhost 指向容器自身，应填写数据库服务名或可达地址。
• 安装后再次出现向导：检查 config 目录是否正确挂载，以及 install.lock 是否被持久化。

下一步：登录管理后台。