Sena Repo 服务端部署说明书
CAUTION
Sena Repo 由 AI 辅助开发,安全性未经过专业审计。强烈建议仅在 VPN 或家庭内网环境中使用,不建议直接暴露到公网。
目录
部署前准备
目录结构
Sena Repo 按固定层级扫描游戏文件,部署前请先整理好文件:
游戏目录/
├── 会社A/
│ ├── 游戏1/
│ │ ├── [PC]游戏1.rar
│ │ └── [KRKR]游戏1_v2.zip
│ └── 游戏2/
│ └── [Ty]游戏2.7z
└── 会社B/
└── 游戏3/
└── 直装_游戏3.apk| 层级 | 内容 |
|---|---|
| 第一级 | 会社文件夹(文件夹名即会社名) |
| 第二级 | 游戏文件夹(文件夹名即游戏名) |
| 第三级 | 压缩包(.rar .zip .7z .tar .gz .xz .apk) |
- 平台标记:
[PC][KRKR][Ty][ONS]直装_,无标记默认 PC - 压缩包直接放在会社目录下也可以,自动视为独立游戏
文件不按规则整理则扫不出来。也可以在设置中调整目录结构为"仅游戏"或"扁平"模式。
如果游戏库和 Steam 补丁库都使用 OpenList 作为文件来源,服务端本地无需挂载实际的 /games 和补丁文件目录。补丁索引与关键词配置都写在数据目录下的 steam_patch_index/,只要 /data 是持久化挂载即可。
压缩包目录结构(建议)
扫描只看压缩包的文件名和它所在的位置,不检查压缩包内部结构;下面是打包建议,不是硬性要求。
游戏压缩包
- 单顶层目录或直接在根目录放散文件,都能正常处理
- 客户端解压后会统一整理成以「版本目录名」命名的文件夹:单顶层目录会被重命名,散文件会被包进这个文件夹
- 建议只套一层目录(例如
游戏名/…),避免多套游戏名/版本/…之类的层级——多出来的层级会原样保留在解压结果里 - 压缩包内建议直接放游戏本体文件,不要混入安装说明、重复的压缩包等无关内容
Steam 补丁压缩包
结构不限,靠 patch_dir / target_dir 适配(见 Steam 补丁注入)。省事的做法是只套一层顶层目录(例如 汉化v2/…):服务端分析压缩包时会自动识别并提示把它作为补丁源目录 patch_dir,直接采用即可。
Steam 补丁目录结构
steam_patch/ ← 补丁压缩包目录(本地类型的补丁库)
├── 游戏1_Steam_Chinese_Patch.7z
└── 游戏2_Steam_Voice_Patch.rar
data/steam_patch_index/ ← 索引目录,位于数据目录内
├── patches.json ← 自动生成,记录所有补丁与匹配规则
└── patch_type_keywords.json ← 补丁类型识别关键词配置服务端部署
方式一:Docker 拉取(推荐)
Release 发布时镜像自动推送到 DockerHub 和 GHCR,同时支持 amd64 和 arm64。
# DockerHub(推荐)
docker pull 404gcross/sena-repo:latest
# GHCR(备用)
docker pull ghcr.io/404-gcross/sena-repo:latest
# Beta 测试版(发布 beta / rc 时更新)
docker pull 404gcross/sena-repo:beta
# Dev 开发版
docker pull 404gcross/sena-repo:dev基础启动:
docker run -d \
--name sena-repo \
-p 11451:11451 \
-v /path/to/games:/games \
-v /path/to/data:/data \
-v /path/to/steam_patches:/steam_patch \
--restart unless-stopped \
404gcross/sena-repo:latest纯 OpenList 启动(游戏文件全在 OpenList 上):
docker run -d \
--name sena-repo \
-p 11451:11451 \
-v /path/to/data:/data \
-e SENA_PATCH_DIR=/data/steam_patch \
--restart unless-stopped \
404gcross/sena-repo:latest完整启动(含刮削 API Key 与代理):
docker run -d \
--name sena-repo \
-p 11451:11451 \
-v /path/to/games:/games \
-v /path/to/data:/data \
-v /path/to/steam_patches:/steam_patch \
-e SENA_BANGUMI_TOKEN="your_token" \
-e SENA_VNDB_TOKEN="your_token" \
-e SENA_PROXY="http://127.0.0.1:7890" \
--restart unless-stopped \
404gcross/sena-repo:latestDocker Compose:
services:
sena-repo:
image: 404gcross/sena-repo:latest
container_name: sena-repo
ports:
- "11451:11451"
volumes:
- /path/to/games:/games
- /path/to/data:/data
- /path/to/steam_patches:/steam_patch
environment:
- SENA_BANGUMI_TOKEN=your_token # 可选
- SENA_VNDB_TOKEN=your_token # 可选
- SENA_PROXY=http://127.0.0.1:7890 # 可选,刮削代理
restart: unless-stopped纯 OpenList Docker Compose:
services:
sena-repo:
image: 404gcross/sena-repo:latest
container_name: sena-repo
ports:
- "11451:11451"
volumes:
- /path/to/data:/data
environment:
- SENA_PATCH_DIR=/data/steam_patch
restart: unless-stoppedDocker 镜像内置 senacli,可以直接在容器里执行本地维护命令:
docker exec -it sena-repo senacli status
docker exec -it sena-repo senacli scan --scrape missing
docker exec -it sena-repo senacli useraddDocker 部署的升级和卸载仍应在宿主机通过重新拉取镜像、停止旧容器、重建容器完成;容器内的 senacli update / senacli uninstall 只会给出操作提示,不会尝试修改宿主机。
方式二:Tarball 加载
从 Releases 下载对应架构的 Sena-Repo_Server_*.tar.gz:
| 架构 | 文件名 |
|---|---|
| x86_64 / amd64 | Sena-Repo_Server_amd64_v*.tar.gz |
| ARM64 | Sena-Repo_Server_arm64_v*.tar.gz |
docker load < Sena-Repo_Server_amd64_v0.1.0.tar.gz
docker run -d \
--name sena-repo \
-p 11451:11451 \
-v /path/to/games:/games \
-v /path/to/data:/data \
-v /path/to/steam_patches:/steam_patch \
sena-repo:latest方式三:安装脚本直接部署
适合没有 Docker 的设备,例如部分 arm32 NAS、盒子或 Armbian 设备。amd64 / arm64 仍建议优先使用 Docker。
一键安装(交互式会让你选版本通道):
# 直连
curl -fsSL https://raw.githubusercontent.com/404-GCross/Sena-Repo/main/server/install.sh | sudo bash
# 国内镜像(只在脚本地址前加前缀;源码拉取会自动跟随,直连失败时也会自动回退到镜像)
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/404-GCross/Sena-Repo/main/server/install.sh | sudo bash直接运行安装脚本时(首次安装或 --update)会让你选择版本通道(直接回车保持当前通道):
- 稳定版:最新正式版 tag
- 测试版:最新预发布(beta / rc)tag
- 开发版:
main分支,滚动最新
非交互环境用 --channel 指定,例如 ... | sudo bash -s -- --channel beta;固定某个版本用 --ref(如 --ref v0.2.0)。选择结果会记入 /opt/sena-repo/.version,之后 --update / senacli update 会继续沿这个通道解析最新版本;直接回车不做选择,保持当前通道。注意 senacli update 不会弹出这个选择,它按记录里的通道升级;要换通道用 senacli update --channel beta|release(或 --ref),也可以重跑安装脚本在提示里选。通道名统一为 dev / beta / release,stable 是 release 的别名。
安装结束时会检测 firewalld / ufw:如果端口未放行会询问是否放行(非交互时打印手动命令)。
如果需要指定端口、数据目录或 Python 路径,可以把环境变量放到 sudo 后面:
curl -fsSL https://raw.githubusercontent.com/404-GCross/Sena-Repo/main/server/install.sh | sudo SENA_PORT=11451 SENA_DATA_PATH=/var/lib/sena-repo bash如果希望先查看脚本内容再执行:
curl -fsSLO https://raw.githubusercontent.com/404-GCross/Sena-Repo/main/server/install.sh
sudo bash install.sh也可以手动 clone 稳定版源码后运行本地脚本:
git clone https://github.com/404-GCross/Sena-Repo.git
cd Sena-Repo/server
sudo bash install.sh国内网络同样给地址加 https://gh-proxy.com/ 前缀即可,例如 git clone https://gh-proxy.com/https://github.com/404-GCross/Sena-Repo.git;先下载脚本再执行、以及带环境变量的命令也同理。
如需固定某个分支或 tag 的源码,把上面命令的 -b 与 SENA_REPO_REF 换成对应 ref 即可(例如滚动开发标签 dev-release,或正式版发布后的 v0.2.0)。
脚本当前支持带 systemd 的常见 Linux 发行版,会自动识别 apt-get、dnf、yum、zypper 或 pacman 安装 Python 编译依赖、创建 venv、写入 systemd 服务并启动服务。已覆盖 Debian / Ubuntu / Armbian、Fedora / RHEL / Rocky / AlmaLinux / openEuler、openSUSE、Arch / Manjaro 等发行版。
如果发行版不在上述包管理器范围内,脚本不会立即退出;只要系统已经手动准备好依赖,仍会继续尝试创建 venv 和安装服务。
如果系统默认 python3 低于 3.10,可以通过环境变量指定 Python:
sudo SENA_PYTHON_BIN=/usr/bin/python3.11 bash install.shSteam 补丁压缩包探测需要 7z / 7zz / 7za。RPM 系发行版如果没有直接安装到 7z,通常需要先启用 EPEL 或手动安装 7zip / p7zip。
如果服务端已经安装,再次直接运行安装脚本时会先检查远程提交版本与本地组件:源码已是最新且组件齐全时才会跳过;检测到新提交、或发现组件缺失(例如 senacli、venv、systemd 单元)时会重新安装并重启服务。需要强制更新可使用 --update,只检查而不更新可使用 --check。
更新过程会先在旧服务仍运行时准备好新代码和独立 Python 环境,再停服切换并轮询 /api/health;健康检查失败会自动回滚到上一份代码并重启。旧代码保留在 /opt/sena-repo/server.prev。
安装完成后会注册本地维护命令 senacli,常用命令如下:
senacli status --roots
senacli scan
senacli scan --scrape missing
senacli clear
senacli backup
senacli backup /path/to/backup-dir
senacli backup -o /path/to/backup.zip
senacli backup --json-only
senacli restore sena-backup-20260915-153000.zip
senacli update
senacli update --check
senacli update --channel beta
senacli update --channel release
senacli uninstall用户管理命令:
senacli users
senacli useradd
senacli username
senacli passwd
senacli useradmin
senacli userdeluseradd 在数据库没有任何用户时会创建首个管理员;已有用户后默认创建普通用户,加 --admin 可创建管理员。username、passwd、useradmin 会让目标用户现有登录态失效,用户需要重新登录。clear 只清理可重建的游戏、版本和游戏标签关联;手动条目、仅元数据条目、已锁定条目,以及目录配置、用户、OpenList 与刮削配置都会保留,然后重新扫描。
日志与审计
服务端日志写入 <data>/logs/:
/var/lib/sena-repo/logs/server.log
/var/lib/sena-repo/logs/cli.log按 5 MB × 5 轮转。当前会记录:
- 登录成功/失败、限流、登出,以及管理员接口的 401/403(含用户、路径、来源 IP)
- 管理员操作:用户、目录、游戏、标签、平台分类、文件源、刮削设置、备份导出/导入/删除等
- 下载链接创建与实际签名下载(含
user_id);备份下载(含账号、文件名、大小) - CLI 命令开始/结束(命令、操作者、耗时、退出码);
senacli useradd/passwd/userdel/useradmin、scan、clear等关键动作有单独事件 - 上传被拒绝(扩展名、大小限制)、平台分类排序、OAuth 授权开始
CLI 参数中的 --password、--token、--api-key、--secret、--proxy 会替换为 ***。异常日志只记录异常类型与脱敏后的消息,不打印完整堆栈和敏感参数。服务端 access log 会去掉签名 URL 的 query;客户端日志按服务器 + 账号隔离,普通用户只能看自己的记录,管理员不能读取其他账号的 personal 下载日志。
连不上怎么排查
按顺序检查(把 <服务器IP> 换成实际地址)。
1. 服务在跑吗
senacli status # 确认 Service active、Bind 是 0.0.0.0:<端口>2. 本机连通性
curl -fsS http://127.0.0.1:11451/api/health # 期望 {"status":"ok","version":"..."}
ss -tlnp | grep 11451 # 期望 0.0.0.0:11451 LISTEN3. 从客户端所在设备测
curl -v http://<服务器IP>:11451/api/health
nc -vz <服务器IP> 114514. 本机能通、外面不通 → 基本都是防火墙
# firewalld(Fedora / RHEL / openEuler)
sudo firewall-cmd --permanent --add-port=11451/tcp && sudo firewall-cmd --reload
# ufw(Ubuntu / Debian)
sudo ufw allow 11451/tcp云主机还要在服务商控制台的安全组放行对应端口;局域网内注意路由器的 AP 隔离或 VLAN 隔离。
5. 客户端设置
地址要带 scheme,例如 http://<服务器IP>:11451(只有走 HTTPS 反代时才勾选 HTTPS);新服务器第一次连接会提示「服务器需要初始化」,跟着向导创建管理员账号即可。
备份与恢复
备份、恢复与从备份重建的完整说明见 备份与恢复。
默认路径与维护
默认路径:
| 路径 | 说明 |
|---|---|
/opt/sena-repo/server | 服务端程序 |
/opt/sena-repo/venv | Python 虚拟环境 |
/etc/sena-repo/sena-repo.env | 服务端环境变量 |
/var/lib/sena-repo | 数据库、封面、配置数据 |
/srv/sena-repo/games | 本地游戏库目录 |
/srv/sena-repo/steam_patch | Steam 补丁目录 |
更新:
sudo bash /opt/sena-repo/install.sh --update更新会从配置的远程仓库和分支拉取最新服务端代码,不使用当前目录中的旧代码;数据库、游戏目录、补丁目录和环境配置会保留。直接运行安装脚本时,交互式终端下会询问版本通道(回车保持当前通道);senacli update 不会询问,它按安装记录里的通道升级。
senacli update 和 senacli status 显示实际构建版本:开发版为 dev-<短提交号>,测试版为 v1.0.0-beta.3 等发布标签,正式版为 v1.0.0 等发布标签。更新通道和提交号单独列出;切换后续更新通道不会改变已经安装的构建标识。根目录 VERSION 只是发布基准,不用于给开发版命名。信息缺失时显示“未知”,更新判断仍比较完整提交号,不依赖显示文本。
准备工作(拉取源码、安装依赖到新的 Python 环境)都在旧服务仍在运行时完成;随后才停服、切换目录、启动,并轮询 /api/health 最长 2 分钟。依赖安装在新 venv 中进行,首次或没有 pip 缓存时需要从 PyPI 下载,可能耗时几分钟;完整 pip 日志写入 /opt/sena-repo/pip-install.log,终端只保留阶段信息和失败时的末尾日志。系统依赖已齐全时会跳过 apt-get update。如果本机 git 缺少 HTTPS helper(例如某些 NAS 商店版),更新会直接走源码 tar 包回退,不再重复尝试 git。健康检查通过才记录新版本号;失败会自动切回上一份代码、恢复环境文件并重启旧版本,命令以非零退出码结束并打印服务日志尾部。更新前如果检测到正在进行的恢复(.restore.lock 被占用),会直接中止。
只检查是否有更新、不执行安装:
sudo bash /opt/sena-repo/install.sh --check退出码:0 已是最新、1 有更新、2 检查失败。senacli update --check 语义相同。
安装脚本会记录上次使用的仓库地址和分支;未显式设置 SENA_REPO_URL / SENA_REPO_REF 时,后续检查会继续使用该记录。
卸载程序文件:
sudo bash /opt/sena-repo/uninstall.sh默认卸载会保留 /var/lib/sena-repo 和 /etc/sena-repo/sena-repo.env,避免误删数据库和配置。需要连数据库与配置一起清除时:
sudo bash /opt/sena-repo/uninstall.sh --purge-data也可以明确保留数据:
sudo bash /opt/sena-repo/uninstall.sh --keep-data不带选项且在交互终端执行时,脚本会询问是否删除;如果程序目录已经被删除但数据库或配置仍在,也会先询问。非交互执行默认保留数据,并提示使用 --purge-data。
配置参考
环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
SENA_GAMES_PATH | 游戏文件目录 | /games |
SENA_DATA_PATH | 数据目录(数据库、封面等) | /data |
SENA_PATCH_DIR | Steam 补丁目录 | /steam_patch |
SENA_HOST | 监听地址 | 0.0.0.0 |
SENA_PORT | 监听端口 | 11451 |
SENA_ALLOWED_ORIGINS | 允许浏览器跨域的来源列表(逗号分隔) | 空(关闭跨域) |
SENA_TOKEN_EXPIRE_DAYS | 登录会话有效期(天) | 30 |
SENA_PROXY | 刮削代理(http/socks5) | 空 |
SENA_BANGUMI_TOKEN | Bangumi API Token | 空 |
SENA_VNDB_TOKEN | VNDB API Token | 空 |
SENA_NEXTMOE_API_KEY | NextMoe 应用密钥(nmk_live_…),OAuth 未绑定时作为后备 | 空 |
SENA_OAUTH_ENABLED | 是否开启 NextMoe OAuth 免密登录 | true |
SENA_OAUTH_CLIENT_ID | 覆盖默认的官方 OAuth 客户端 ID | 官方内置 |
SENA_OAUTH_ISSUER | NextMoe OAuth 服务地址 | https://account.nextmoe.com/api/v1 |
SENA_OAUTH_SCOPES | NextMoe OAuth scope | openid profile catalog:read |
SENA_OAUTH_HIKARINAGI_ENABLED | 是否开启 Hikarinagi OAuth 登录与绑定 | true |
SENA_OAUTH_HIKARINAGI_CLIENT_ID | Hikarinagi public client ID | 官方内置 |
SENA_OAUTH_HIKARINAGI_ISSUER | Hikarinagi OIDC 地址 | https://id.hikarinagi.org/oidc |
SENA_OAUTH_HIKARINAGI_SCOPES | Hikarinagi OAuth scope | openid profile offline_access catalog:full user:read |
config.yaml(可选)
/data/config.yaml 可覆盖部分配置(环境变量优先级更高):
server:
host: 0.0.0.0
port: 11451
allowed_origins: []
token_expire_days: 30
games_path: /games
data_path: /data
patch_dir: /steam_patch
steam_dir: ""
proxy: ""
scrapers:
bangumi_token: ""
vndb_token: ""
hikarinagi_client_id: ""
hikarinagi_client_secret: ""
nextmoe_api_key: ""
oauth:
enabled: true
issuer: "https://account.nextmoe.com/api/v1"
client_id: ""
scopes: "openid profile catalog:read"
providers:
nextmoe:
enabled: true
hikarinagi:
enabled: true
issuer: "https://id.hikarinagi.org/oidc"
client_id: ""
scopes: "openid profile offline_access catalog:full user:read"
redirect_uri: "http://127.0.0.1:11453/callback"
prompt: "consent"
numeric_user_id: trueHikarinagi 开发者后台需为应用启用 user:read,服务端在验证 ID token 后通过 /v3/user/me 读取数字用户 ID,用于管理员预绑定和首次授权登录。旧配置也会补入此必需权限;旧授权需重新授权,新权限不会自动附加到原令牌。已有绑定会在下一次成功授权时补全数字 ID,无需数据库迁移。
数据目录结构
/data/
├── sena_repo.db ← SQLite 数据库
├── covers/ ← 游戏封面图
├── backgrounds/ ← 游戏背景图
├── avatars/ ← 用户头像
├── scan_settings.json ← 扫描配置持久化
└── scraper_config.json ← 刮削配置持久化刮削源
| 刮削源 | 认证要求 | 说明 |
|---|---|---|
| VNDB | 可选 Token | 含游戏时长数据 |
| Bangumi | 可选 Token | 中文元数据丰富 |
| Steam | 免认证 | 封面、背景、简介 |
| Hikarinagi | Client ID / Secret | 中文 Galgame 资料站 |
| NextMoe | OAuth 绑定或应用密钥 | 聚合六源;独立模式,开启后禁用其他刮削源;含游戏时长(仅详情) |
NextMoe 是独立的刮削模式:在客户端「扫描设置 → 刮削源」中开启 NextMoe 后,其余刮削源会自动关闭并禁用,单条目和批量刮削都只走 NextMoe。关闭 NextMoe 后其余刮削源恢复可选。
认证优先走 OAuth:用户在客户端用 NextMoe 账号登录或在「我的 → 个人信息」绑定后,单条目刮削使用该账号自己的授权。也可以继续使用
SENA_NEXTMOE_API_KEY(在 https://developer.nextmoe.dev 控制台创建应用并勾选catalog:read,免费额度为每分钟 60 次、每天 50000 次)作为后备。OAuth 默认启用官方客户端 ID,可用SENA_OAUTH_CLIENT_ID覆盖。Hikarinagi 同样优先使用用户绑定的 OAuth 令牌:服务端把令牌加密保存在绑定记录中,并自动续期;用户令牌失效时会提示重新授权,不会静默改用其他账号。未绑定时继续使用
hikarinagi_client_id/hikarinagi_client_secret应用凭据。定时扫描使用服务端应用凭据。升级到多提供方版本后,服务端首次启动会自动把旧
users.oauth_*中的 NextMoe 绑定回填到新表;不需要手动执行迁移。回填只执行一次,之后解除的绑定不会在重启时恢复。
游戏时长来自 NextMoe 详情接口的
playtimes块(多上游并列,服务端优先取nextmoe聚合行、否则取票数最多的行)。由于列表接口不返回该字段,只有单条目刮削(详情)会写入平均时长,批量刮削不会写入,也不额外请求详情。
别名自动填充:VNDB(
aliases)、Bangumi(infobox「别名」)、Hikarinagi(aliases)和 NextMoe(titles中title_kind=alias,不收缩写,机器翻译保留但排最后)会在刮削时提取别名,去重后以「、」拼接写入游戏别名(最多 5 条、200 字符)。「补全缺失」只填空,「覆盖」会替换已有别名;Steam 无别名数据。
OpenList 文件源
OpenList 的添加方式与下载链路见 文件源接入。
Steam 补丁
工作原理
补丁文件(.7z/.rar/.zip 等)
│
扫描 → patches.json(记录 AppID、文件路径、类型等)
│
客户端扫描本地 steamapps → 匹配 AppID → 下载注入AppID 识别规则(优先级从高到低)
- 文件名中的纯数字(
123456.zip→ 123456) - 父目录名中的纯数字(
123456/patch.zip→ 123456) - 从文件名提取游戏名 → Steam Store API 搜索
- 都失败则
app_id: null,可手动在客户端填写
补丁类型识别关键词
| 类型 | 默认关键词 |
|---|---|
translation(汉化) | _Steam_Chinese_Patch |
voice(音声) | _Steam_Voice_Patch |
story(剧情) | _Steam_Story_Patch |
extra(额外) | _Steam_Extra_Patch |
misc(其他) | 无关键词匹配时 |
关键词文件位于数据目录的 steam_patch_index/patch_type_keywords.json,可在客户端 Steam 补丁页的「关键词匹配」里编辑,也可以直接改这个文件。文件名(统一转小写)包含任一关键词即归为该类型,按类型顺序取第一个命中的;misc 不参与匹配。
这份文件只在不存在时才会写入上面的默认值,之后以文件内容为准——也就是说修改过关键词后,升级服务端不会覆盖你改过的词。它会被 senacli backup 一起导出,senacli restore 默认一起恢复(加 --skip-keywords 可保留服务器上的现有词表)。
patches.json 字段说明
| 字段 | 说明 |
|---|---|
app_id | Steam AppID |
file | 压缩包相对补丁目录的路径 |
patch_dir | 解压后取哪个子目录的内容(空=自动选) |
target_dir | 复制到游戏目录的哪个子路径(空=根目录) |
label | 界面显示名称 |
type | 补丁类型 |
game_name | Steam 游戏中文名 |
附录
支持的压缩格式
.zip .rar .7z .tar .gz .xz .apk
平台标识
| 标识 | 平台 |
|---|---|
[PC] | Windows PC |
[KRKR] | Kirikiri |
[Ty] | Tyranor |
[ONS] | ONScripter |
直装_ / .apk | Android 直装 |
默认端口
11451 — 服务端 HTTP API