Sena Repo

Appearance

Sena Repo 客户端使用说明书 ​

Sena Repo 客户端用于连接 Sena Repo 服务端，浏览游戏库、下载并解压游戏、导入 Steam 非 Steam 游戏，以及注入 Steam 汉化补丁。当前支持 Windows、Android 和 Linux。

目录 ​

安装 ​

从 GitHub Releases 下载对应平台的客户端：

平台文件说明
Windows.exe 安装包 / .zip 便携版推荐安装版；便携版解压后直接运行
Android.apk需要授予文件访问权限
Linux.AppImage适合桌面 Linux / 掌机系统

Windows 和 Linux 客户端内置 7zip-zstd 解压组件。Android 使用应用内下载与解压流程，不显示 Steam 相关功能。

首次启动 ​

客户端首次启动时会弹出免责声明，同意后进入本机设置：

  • 游戏下载目录 — 下载的游戏压缩包和解压后文件存放位置
  • Steam steamapps 目录 — 用于 Steam 补丁匹配，填写 Steam 库的 steamapps 文件夹路径
  • Steam 用户 ID — Steam 好友代码，也可在 Steam 安装目录 userdata 文件夹中找到纯数字目录名

这些设置保存在本设备，不写入服务端。之后可在登录/服务器选择界面右上角的齿轮按钮修改，或在「设置 → 下载设置」中更改。

连接服务器 ​

添加服务器 ​

在服务器选择界面点击「添加服务器」，进入二级界面填写：

  • 配置名称
  • 服务器地址（IP 或域名）
  • 端口（默认 11451）
  • 是否使用 HTTPS
  • 用户名和密码

保存后作为一条服务器配置显示在列表中。每条配置右侧的三点菜单可编辑或删除；编辑服务器地址、协议、用户名或密码后相当于重新登录该配置。

自动登录 ​

客户端启动时会优先尝试自动登录上次使用的服务器配置。启动时会请求 /api/auth/profile/me 检查保存的 token 是否仍然有效：

  • token 有效 → 直接进入游戏库
  • token 过期或服务端已重置 → 弹出重新登录或初始化流程
  • 连接异常 → 弹窗提示连接失败，不会静默失败

退出登录 ​

在「我的」界面点击「退出登录」，回到服务器选择界面。退出只清除当前激活会话，不删除已保存的服务器配置。

首次初始化服务端 ​

连接到未初始化的服务端时，客户端会进入服务端初始化向导：

第零步：选择初始化方式

  • 新建服务端 — 走下面的三步向导，从零开始配置
  • 导入备份 — 选择 senacli backup 导出的 .zip（或 --json-only 导出的 .json）上传，服务端会恢复游戏库、补丁规则、账号和封面图片。导入完成后用备份里的账号登录，向导直接结束

第一步：创建管理员 填写首个管理员的用户名和密码。

第二步：配置目录与刮削

  • 游戏库目录（可添加多个，支持本地路径或 OpenList 源）
  • Steam 补丁库目录
  • 批量刮削字段来源配置（封面用哪个源、简介用哪个源等）
  • 自动扫描开关与间隔

第三步（可选）：本地配置 确认客户端本机的下载目录和 Steam 目录。

初始化完成后，服务端会在后台自动触发首次扫描和刮削。

OpenList 文件源 ​

在第二步配置目录时，游戏库目录和 Steam 补丁库目录都可以选择本地路径或 OpenList 文件源：

  1. 添加 OpenList 服务器，填写地址、用户名和密码；留空时使用 OpenList 访客模式。
  2. 填写 OpenList 地址，例如 http://192.168.1.100:5244。如果遗漏协议，服务端会尝试补 http://。
  3. 添加游戏库目录或 Steam 补丁目录时选择该 OpenList 服务器。
  4. 填写 OpenList 内部路径，例如 /115/Games/GalGame/Library。
  5. 选择目录结构 / 游戏目录深度。

OpenList 地址必须同时能被 Sena 服务端和客户端设备访问；只在服务端可访问会导致扫描成功但客户端下载失败。服务端侧的部署方式和下载链路见 OpenList 文件源。

游戏库浏览 ​

进入游戏库后：

  • 网格/列表视图切换 — 在上方工具栏「筛选与显示方式」面板里切换
  • 搜索 — 顶部搜索栏实时过滤
  • 排序 — 按导入时间、名称、别名、会社、游玩时长排序
  • 筛选 — 按标签、平台筛选；多条件可叠加
  • 下拉刷新 — 列表顶部下拉重新加载

游戏详情与下载 ​

点击游戏进入详情页，显示封面、背景图、简介、标签、版本列表。

下载游戏 ​

  1. 点击版本右侧「下载」按钮
  2. 下载进度在页面底部/通知栏显示
  3. 下载完成后弹出操作选项：
    • 解压 — 解压到下载目录
    • 创建快捷方式（Windows）
    • 导入 Steam（Windows/Linux）
    • 打开文件夹 — 打开解压目标文件夹
  4. 如果版本预设了解压密码，解压时自动使用；有密码但解压失败时弹窗提示

取消下载 ​

下载弹窗中点击取消，终止当前下载任务并清理临时文件。

元数据编辑（管理员） ​

游戏详情页右上角菜单可进入编辑界面：

  • 修改名称、别名、会社、简介、发行日期等文字字段
  • 修改封面/背景图（上传本地文件或粘贴 URL）
  • 按版本修改平台分类（PC / KRKR 等）
  • 按版本设置解压密码
  • 按版本移动到其他游戏条目

Steam 集成 ​

Steam 集成功能仅在 Windows 和 Linux 上显示。

导入 Steam ​

下载解压完成后选择「导入 Steam」，客户端会将游戏以非 Steam 游戏的形式添加到 Steam 库，并尝试设置游戏图标。

需要在首次启动时正确填写 Steam steamapps 目录和 Steam 用户 ID。

Steam 补丁注入 ​

Steam 补丁页面分为「补丁注入」和「补丁配置」两个 Tab：前者在客户端执行扫描与注入，后者在服务端维护补丁匹配与类型关键词。

补丁注入 Tab：

  1. 点击「扫描 Steam 库」，客户端读取本地 steamapps 目录并发送游戏列表给服务端
  2. 服务端根据 patches.json 匹配 AppID
  3. 匹配到的游戏会显示可用补丁列表
  4. 补丁规则已配置时显示「注入」，点击后下载补丁压缩包并解压到对应游戏目录；规则未配置时按钮显示「规则待配置」，需要先在「补丁配置」中配置规则

补丁下载走的是签名直链（POST /api/steam/patches/{key}/link 取一次带时效的 URL），因此和游戏下载共用同一条管线：优先交给内置 aria2 多连接下载，失败再退回分片/流式；网盘上的补丁还会按来源类型用浏览器 UA 和分片降级重试。链接过期时客户端会自动换一条新的继续下。

补丁配置 Tab（管理员）：

  • 查看和编辑 patches.json 中的补丁条目
  • 手动触发补丁扫描
  • 通过右上角「关键词匹配」编辑类型识别关键词
  • 每行右侧可以锁定元数据：锁上后自动扫描与「重新刮削 AppID」都不会改动这条的 AppID、游戏名、标签、类型与注入规则（文件大小、来源路径这类文件事实仍会随扫描更新），再点一次解锁

设置 ​

进入「我的 → 设置」：

扫描设置（管理员） ​

  • 查看和管理游戏库根目录
  • 手动触发扫描
  • 开关自动扫描、设置扫描间隔
  • 调整目录结构（会社/游戏、仅游戏、扁平）
  • 清空游戏库并重新扫描
  • 管理 OpenList 服务器

刮削设置（管理员） ​

  • 配置 Bangumi / VNDB API Token
  • 配置代理
  • 设置批量自动刮削的字段来源规则

下载设置 ​

  • 最大同时下载数（最高 10）
  • 下载目录
  • 下载限速（KB/s，0 为不限速）
  • 快捷方式保存位置（Windows）

备份与恢复（管理员） ​

「设置 → 服务端 → 备份与恢复」：

  • 导出备份 — 先选备份范围：仅游戏库（游戏、版本、标签、账号）、仅补丁（匹配规则 + 类型关键词）或两个都备份；选游戏库时可以勾选是否包含封面/背景/头像。生成后出现在下面的列表里，文件名里带范围标识（例如 …-patch-….json）
  • 备份列表 — 显示服务端上已有的备份：文件名、大小、时间、是否含图片；每行可以「下载」（桌面端选保存位置，手机端存到应用目录并提示路径）或「删除」
  • 导入备份 — 选择 zip/JSON 上传，导入前先选：恢复范围（全部 / 仅补丁规则 / 仅游戏库与账号）、已存在条目怎么处理（合并更新 / 清空重建）、同名图片怎么处理（跳过 / 覆盖）；导入完成后弹出各项统计

备份文件里有账号密码哈希与解压密码，请妥善保管。

显示设置 ​

  • 封面大小
  • 外观偏好
  • 主题色

客户端本地设置 ​

登录/服务器选择界面右上角齿轮按钮，可修改：

  • 游戏下载目录
  • Steam steamapps 目录
  • Steam 用户 ID

用户与通知 ​

注册 ​

在登录界面点击注册，提交后需等待管理员审批方可登录。

管理员审批 ​

管理员可在：

  • 通知页审批注册请求
  • 「设置 → 用户管理」中审批或拒绝用户、授予或撤销管理员权限

审批完成后对应通知自动标记已读。

Linux 触屏 ​

Linux AppImage 针对 Wayland、X11、Gamescope、Bazzite 等环境做了触屏兼容处理，启动时自动优先 GDK_BACKEND=wayland,x11。

用终端启动可查看触屏诊断日志：

bash
./Sena-Repo_Linux_v*.AppImage 2>&1 | tee sena-touch.log

正常情况下触摸屏幕会输出：

Sena Linux touch event: begin x=... y=...
Sena Linux touch event: update x=... y=...

如果有日志但界面无响应，请反馈日志中的 backend 和 widget 字段。

排障 ​

点击服务器无反应 ​

检查：

  1. 服务器地址和端口是否填写正确
  2. 是否选择了正确的 HTTP/HTTPS 协议
  3. 服务端 /api/health 是否可访问
  4. token 是否过期，必要时从服务器配置菜单重新登录

下载报 401 ​

保存的登录 token 已失效。回到服务器选择界面，点击对应配置重新登录。

OpenList 下载卡住 ​

查看客户端日志中的 download request / download redirect 序列，判断卡在哪一跳：

  • 卡在第一跳：客户端到 Sena 服务端不通
  • 卡在第二跳：客户端访问不了 OpenList 地址（OpenList 地址必须客户端可访问）
  • 卡在第三跳：CDN 对当前网络有限制

Android 安装 APK 失败 ​

报错类似 Failed to find configured root that contains .../xxx.apk，通常是安装来源路径不在应用可共享目录下。将下载目录设置到 Android 公共下载文件夹并确认已授予文件访问权限。

相关文档 ​

Released under the AGPL v3 License.

Copyright © 2026 Sena Repo