OneOpenlistEo

OneOpenlistEo 完整部署文档

文档日期：2026.8.14
适用仓库：openlist-eo（OpenList-Worker → EdgeOne Makers 无服务器移植版）
文档目标：从零到可访问生产环境，覆盖介绍、架构、功能、本地/云端部署、流水线与扩展。

版权

这里十分感谢@时光大佬提供的思路❤️❤️❤️，然后由@One借助咸鱼cursor来完成openlist-eo版的开发，亲测十分丝滑哦。

效果

效果demo：https://openlisteo.onedayxyy.cn/s/oneyp

开源仓库

https://cnb.cool/onedayxyy/OneOpenlistEoPublic

1. 项目介绍

OneOpenlistEo（openlist-eo） 是将 OpenList-Worker 适配到腾讯云 EdgeOne Makers 的无服务器云盘网关。

它解决的核心问题是：

• 不想买/维护云服务器，但仍需要网盘聚合、文件浏览、预览与分享；
• 大文件下载/预览尽量走网盘 302 直链，避免把流量打穿边缘函数；
• 前端、API、下载、分享页统一部署在 EdgeOne 上，一条命令（或一次 git push）即可发版。

定位说明：上游 OpenList-Worker 仍在演进，本仓库目标是「零服务器可用」，并非 100% 复刻 Docker 完整版 OpenList。部分管理能力（索引、加密落地、部分驱动细节）可能与规划文档不完全一致，以线上实际行为为准。

2. 项目特色

2.1 零服务器

• 不依赖常驻 VPS / Docker。
• 静态资源由 EdgeOne Pages/Makers 托管；API 与下载路由走 Cloud Functions。

2.2 302 直链优先（省流量、提体验）

• 下载/预览链路优先返回网盘直链（/d/*、/sd/* 等）。
• 大视频、大图由浏览器直连 CDN/网盘节点，函数只做鉴权与跳转。
• 强烈建议：挂载驱动时选择 302，不要打开「网页代理/本机中转」（否则流量与延迟都会变差）。

2.3 文件夹分享 + 公开预览

• 支持创建分享、密码、自定义短链（/s/:sid）。
• 分享页支持目录深链（刷新不丢路径）、图片缩略图、视频预览等。
• 分享下载走 /sd/:sid/...，无需登录。

2.4 多网盘驱动

内置多类驱动（能力因上游完成度而异），例如：

• 天翼云盘、移动云盘、115、123、百度、阿里、夸克、迅雷、微云、沃盘
• Google Drive、OneDrive、Yandex、PikPak、TeraBox、TelDrive
• WebDAV、S3、Seafile、SFTP、Cloudreve V4、OpenList、网易云音乐等

本仓库重点验证场景：天翼云盘 + 302 + 文件夹分享。

2.5 双路径发版

2.6 SPA + API 同域

• 根目录 middleware.js 做 SPA rewrite：前端路由刷新不 404。
• API / 下载 / WebDAV / 分享下载路径透传给函数，互不抢路由。

3. 项目架构

3.1 总览

 1浏览器
 2  ├─ 静态前端（Vite/React → public/）
 3  │     /files  /s/:sid  /login  /admin/...
 4  └─ 动态路径
 5        /api/*  /d/*  /p/*  /sd/*  /dav/*  /@setup/*  /ping
 6             └─ middleware.js（透传 or rewrite 到 /）
 7                  └─ cloud-functions/[[default]].js  (Hono onRequest)
 8                       ├─ EdgeOne Blob KV（默认，BLOB_STORE）
 9                       └─ 可选 REMOTE_D1（MySQL/Postgres 等）
10                            └─ 各网盘驱动 → 302 直链 / API

3.2 目录结构（关键路径）

3.3 构建产物流水线

 1npm run install:all
 2        │
 3        ├─ 根目录依赖 + prisma generate
 4        └─ pages/ 前端依赖
 5
 6npm run build
 7        │
 8        ├─ build:backend  → esbuild src/eo/entry.ts
 9        │                   → cloud-functions/[[default]].js
10        └─ build:frontend → vite build
11                            → public/（静态资源）
12
13edgeone makers deploy
14        │
15        └─ 上传静态层 + Cloud Functions + middleware

3.4 请求分层（逻辑）

1. 前端层：React Router 负责页面；Axios/Fetch 调 /api/*。
2. 网关层：middleware.js 区分静态、SPA、API。
3. 应用层：Hono 中间件（CORS、日志、鉴权）+ 路由模块。
4. 领域层：MountManage / FilesManage / ShareManage / UsersManage 等。
5. 驱动层：BasicDriver + 各网盘 files.ts / utils.ts。
6. 持久化层：默认 Blob KV；可选远程 SQL。

3.5 与 Cloudflare 原版差异

4. 项目功能

4.1 面向访客 / 分享用户

4.2 面向登录用户

4.3 面向管理员

4.4 主要 API 面（后端）

5. 环境准备

5.1 软件要求

Windows（PowerShell）与 Linux/macOS（Bash）均可；下文同时给出常见命令。

5.2 获取代码

1git clone https://cnb.cool/onedayxyy/openlisteo.git
2cd openlisteo

若使用本机已有目录（例如 d:\openlist-eo），直接进入即可。

5.3 安装 EdgeOne CLI

1npm i -g edgeone
2edgeone -v
3# 确认 ≥ 1.6.0；过低请重装

5.4 准备密钥与令牌

6. 部署细节（手把手）

6.1 安装项目依赖

1# 根目录 + pages 前端一并安装
2npm run install:all

该命令等价于：

1npm install
2npm install --prefix pages

根目录 postinstall 会执行 prisma generate（远程库场景需要）。

6.2 配置本地 .env

1# Windows
2copy .env.example .env
3
4# Linux / macOS
5cp .env.example .env

编辑 .env（示例）：

1JWT_SECRET=请替换为足够长的随机字符串
2ENABLE_D1=false
3REMOTE_D1=
4BLOB_STORE=openlist-meta-v4
5TMDB_API_KEY=

.env 已在 .gitignore 中，不要提交到仓库。

6.3 登录 EdgeOne

先确认 CLI 环境变量（Skill / 推荐习惯）：

1# Windows PowerShell
2$env:PAGES_SOURCE="skills"
3
4# Bash
5export PAGES_SOURCE=skills

登录（二选一站点，不要猜）：

1edgeone login --site china
2# 或
3edgeone login --site global

无头/CI 环境可用 Token：

1edgeone login --token "你的_EDGEONE_API_TOKEN"

检查登录状态：

1edgeone whoami

6.4 把环境变量同步到远程（生产必做）

本地 .env 不会自动变成线上配置，部署前请写入 Makers 环境变量：

1# PowerShell 示例
2$env:PAGES_SOURCE="skills"
3edgeone makers env set JWT_SECRET "你的密钥"
4edgeone makers env set ENABLE_D1 "false"
5edgeone makers env set BLOB_STORE "openlist-meta-v4"
6# 可选
7# edgeone makers env set TMDB_API_KEY "xxxx"
8# edgeone makers env set REMOTE_D1 "mysql://user:pass@host:3306/db"

也可在腾讯云控制台对应项目的环境变量页手动配置，效果相同。

6.5 本地开发联调

1# 方式 A：一键（先编后端再起 makers 网关）
2npm run dev
3
4# 方式 B：分步
5npm run build
6$env:PAGES_SOURCE="skills"   # Bash: export PAGES_SOURCE=skills
7edgeone makers dev

浏览器打开本地地址（通常为）：

1http://127.0.0.1:8088/

说明：

• 本地开发也应走 edgeone makers dev，以便 Blob / 函数行为贴近线上；
• 改后端后需重新 npm run build:backend（或完整 build）；
• 改前端可在 pages 下按 Vite 习惯热更新（以实际 makers 代理行为为准）。

6.6 本地一键部署到生产

1# PowerShell
2$env:PAGES_SOURCE="skills"
3npm run deploy
4
5# 或预发环境
6npm run deploy:preview

npm run deploy 内部流程：

1. npm run build（后端 + 前端）
2. edgeone makers deploy

部署成功后，CLI 会输出访问 URL。若 URL 带 ?eo_token=...&eo_time=...：

• 必须整段复制（含 query），截断会导致 401；
• Token 可能有时效，过期后从控制台或重新 whoami/部署输出获取。

控制台入口（示例形态）：

1https://console.cloud.tencent.com/edgeone/pages

在项目列表中找到 openlist-eo（或你部署时指定的名称）查看域名、日志、环境变量。

6.7 仅构建、不部署

1npm run build

检查产物：

• cloud-functions/[[default]].js 存在
• public/ 下有 index.html 与静态资源
• 根目录仍有 middleware.js

6.8 自定义项目名部署

CNB 与本地默认项目名为 openlist-eo。若要新建站点：

1$env:PAGES_SOURCE="skills"
2npx --yes edgeone@latest makers deploy -n 你的项目名 --json

首次会创建项目；之后同名即更新。

6.9 Windows / Linux 命令对照

7. 上线后初始化与使用

7.1 首次打开站点

1. 浏览器访问部署 URL（带完整 query，如有）。
2. 按页面引导完成 系统初始化（/@setup/*）。
3. 使用管理员账号登录。

若沿用演示初始账号，请立刻改密：

• 用户名长度等规则以系统校验为准（常见示例：admin）
• 初始密码若为弱口令，上线后必须修改

7.2 添加天翼云盘挂载（推荐路径）

1. 登录 → 管理 → 挂载管理（/admin/mounts）。
2. 选择驱动 天翼云盘（cloud189）。
3. 按字段填写登录方式（客户端/网页 Cookie 等，以表单为准）。
4. 下载/预览策略选择 302。
5. 保存后回到 文件 页浏览挂载路径。

7.3 创建文件夹分享并验证

1. 在文件管理中对目标文件夹创建分享（或「我的分享」）。
2. 可设置密码；可填写自定义短链（字母数字中文、下划线、中划线，2–48 字符，避开保留字）。
3. 打开 /s/<短链或UUID>，验证：
   • 目录进入与刷新 URL 是否保持；
   • 图片缩略图、视频预览；
   • 下载是否跳转到网盘直链（浏览器网络面板可见 302）。

7.4 健康检查

1GET /ping
2GET /api/system/health   # 若已启用

函数正常时应返回成功响应；若 5xx，优先查 JWT_SECRET、Blob、构建产物是否缺失。

8. CNB 云原生流水线

8.1 触发条件

仓库根目录 .cnb.yml 已配置：

• 分支：main
• 事件：push
• 流水线名：build-and-deploy

推送到 main 后自动：安装依赖 → 构建 → EdgeOne 部署 → 统计耗时 → 钉钉通知。

8.2 流水线阶段说明

密钥通过 imports 注入：

1imports:
2  - https://cnb.cool/onedayxyy/secret/-/blob/main/envs.yml

密钥仓库至少应包含：

8.3 推荐发版流程（正式）

1本地改代码 → git add/commit → git push origin main
2        → CNB 自动构建部署 → 钉钉通知 → 浏览器验证

8.4 本地部署 vs 流水线

建议：联调用本地；合并到 main 的正式版本走 CNB，避免「只本地上了线、仓库代码未推送」。

8.5 推送后如何确认

1. 打开 CNB 仓库的 构建/流水线 页面，查看 build-and-deploy 是否成功。
2. 若 deploy 阶段打印「未注入 EDGEONE_API_TOKEN」，检查密钥仓库与 imports 权限。
3. 收到钉钉通知后，用线上 URL 验证分享页与 /ping。

9. 运维与故障排查

9.1 常见问题

9.2 日志与清理

本地调试可能产生（均已忽略提交）：

• deploy*.log、npm-*.log
• *.cookie、curl-*、create-*.json、live-*

定期清理根目录残留，保持仓库干净。

9.3 回滚思路

1. git revert / 回退到已知好的 commit 并 push main，让 CNB 重新部署；或
2. 本地 checkout 旧版本后 npm run deploy（紧急）。

元数据在 Blob / 远程库中，代码回滚不会自动清空挂载与分享配置；更换 BLOB_STORE 相当于换空库，慎用。

9.4 安全建议

• 生产 JWT_SECRET 使用高熵随机串，且勿提交 Git。
• EDGEONE_API_TOKEN、钉钉 Webhook 只放密钥仓库。
• 初始化后立刻修改默认管理员密码。
• 分享链接注意权限与过期策略；自定义短链避免使用保留字（api、admin、assets 等）。

10. 扩展与总结

10.1 可扩展方向

10.2 架构扩展注意点

• 后端入口请继续保持 src/eo/entry.ts → esbuild 产物，勿直接手改 cloud-functions/。
• 新增 API 路由时：同步考虑 middleware.js 的 PASS_THROUGH（若新路径需进函数）。
• 分享/下载等公开路径必须加入鉴权白名单（见 src/route/index.ts 的 PUBLIC_ROUTE_PREFIXES）。
• Prisma 相关代码路径主要为远程库模式服务；默认 Blob 模式不要强行引入重型 DB 依赖到冷启动路径。

10.3 总结

OneOpenlistEo 用 EdgeOne Makers 把 OpenList-Worker 变成「可分享、可 302、可 CI」的无服务器网盘前端：

1. 装依赖 → 配 JWT_SECRET → 登录 EdgeOne → 同步远程环境变量；
2. 日常开发用 npm run dev；
3. 正式发布优先 push main 走 CNB；联调可用本地 npm run deploy；
4. 挂载网盘时坚持 302；用分享页验收预览与下载；
5. 密钥进密钥仓库，产物目录不进 Git，根目录调试垃圾及时清理。

按本文第 5–8 章顺序操作，即可从零完成一套可对外访问的生产部署，并具备可持续发版能力。

11. 附录

A. npm scripts 速查

B. 关键路由速查

C. REMOTE_D1 连接串格式（启用远程库时）

1mysql://<user>:<pass>@<host>:<port>/<db>
2maria://<user>:<pass>@<host>:<port>/<db>
3pgsql://<user>:<pass>@<host>:<port>/<db>
4postgres://<user>:<pass>@<host>:<port>/<db>
5sqlserver://<host>:<port>;database=<db>;username=<u>;password=<p>

同时设置：

1ENABLE_D1=true
2REMOTE_D1=<上述连接串>

D. 相关链接

• EdgeOne Pages / Makers 控制台：https://console.cloud.tencent.com/edgeone/pages
• CNB 使用 EdgeOne 插件参考：https://pages.edgeone.ai/zh/document/using-cnb-plugin
• CNB 配置说明：https://docs.cnb.cool/zh/build/configuration.html
• 上游 OpenList-Worker：https://github.com/OpenListTeam/OpenList-Worker
• 本仓库远程示例：https://cnb.cool/onedayxyy/openlisteo
• 密钥仓库示例：https://cnb.cool/onedayxyy/secret

E. 文档修订

— End of OneOpenlistEo部署文档-2026.8.14 —