OneYp

OneYp 个人云盘 · 完整部署文档

版权

来自@One，one是小白，让Cursor写的。🤣

0.文档说明

文档更新日期：2026-08-08

本地私有仓库：D:\oneyp,（远程：https://cnb.cool/onedayxyy/oneyp）

本地公开仓库：/d/我的开源项目/oneypp，远程开源库：https://cnb.cool/onedayxyy/oneypp

线上环境以你当前 EdgeOne / 七牛实际配置为准；本文不包含任何真实密钥。密钥只放在 EdgeOne 控制台、本地 .env 或 CNB Secret 中。

文档怎么分工（互链）

建议：日常对照勾选用 DEPLOY.md；首次部署或排障读本文；功能与仓库概览看 README.md。

1. 项目简介

OneYP（OneYp）是一款面向个人 / 小团队的可分享云盘：管理员在后台管理目录与文件，通过链接把目录或单个文件分享给访客；访客在独立门户浏览与预览，无需注册。

技术路线与 OneImg 同构：(OneImg开源库：https://cnb.cool/onedayxyy/oneimgpublic)

定位：轻量、可自托管配置、双域名分流（管理 / 分享），适合个人网盘、作品集分享、临时文件分发等场景。

2. 项目优势

1. 边缘部署、运维成本低
   无自建 Node 服务与数据库；Pages Functions + KV + 对象存储即可上线。

2. 双域名清晰隔离
   oneypa.* 管后台，oneyp.* 走分享门户，同一 Pages 项目、同一套代码，按 Host 分流。

3. 多存储可切换
   后台「设置」图形化配置七牛或 S3 兼容；同一时间只启用一套，冷启动可用环境变量 QINIU_* 兜底。

4. 大文件友好
   ≤20MB 可走 Function 上传；更大文件优先浏览器直传对象存储（七牛表单 / S3 预签名 PUT），减轻边缘函数体积与超时压力。

5. 私有桶也能预览 🟢🟢🟢 媒体默认经同源 /api/.../media 代理（支持 Range），CDN 未绑好或私有桶时仍可预览。

6. 分享可控
   可选密码、过期时间、自定义 slug；密码错误有递增限流，降低爆破风险。

7. 自动化发布
   CNB 流水线写版本戳、部署 EdgeOne，可选钉钉通知；提交命中监控路径才触发，避免无效构建。

8. 本地可完整调试
   scripts/local-server.mjs 模拟 Functions + 内存 KV，便于改 API / 前端而不必每次上线。

3. 项目功能

3.1 管理端（oneypa）

3.2 分享端（oneyp）

3.3 运维与诊断

• GET /api/health — 存活与版本
• GET /api/version — 版本字符串
• GET /api/setup/status — 部署就绪诊断（无需登录即可看大体状态；敏感细节以控制台与设置页为准）
• 存储「测试连接」：上传并删除探测对象 _oneyp_test_/ping-*.txt

4. 架构概览

 1浏览器
 2  ├─ oneypa.onedayxyy.cn  → 管理后台（登录 / 文件 / 分享 / 存储设置）
 3  └─ oneyp.onedayxyy.cn   → 访客分享门户 /s/{id}
 4
 5EdgeOne Pages 项目「oneyp」
 6  ├─ Functions
 7  │     ├─ functions/index.js          GET /（按 Host 分流登录页 / 门户）
 8  │     └─ functions/[[default]].js    API + SPA 回落
 9  ├─ 静态资源 public/（outputDirectory）
10  └─ KV：ADMIN_KV
11        ├─ share:* / share_index          分享记录（索引最多约 500 条）
12        ├─ folder-order:*                 目录排序
13        ├─ ratelimit:*                    登录 / 分享密码限流
14        └─ storage:config                 多存储配置（后台「设置」写入）
15
16对象存储（同一时间只启用一套）
17  ├─ 七牛 Kodo（冷启动可用 QINIU_*；支持 vframe 视频封面）
18  └─ 或 S3 兼容（OSS / COS / MinIO 等；视频封面多为占位）

域名分流规则（functions/index.js）：

请求大致路径：

1GET  /                    → 登录页或分享门户首页（按 Host）
2*    /api/*               → Functions API
3*    /admin/*             → public/admin/index.html
4*    /s/* 、 /share/*     → public/share/index.html
5静态 /js 、 /css 等       → public/

5. 当前线上资源对照

开源脱敏副本本地路径（若有）：D:\我的开源项目\oneypp（不含 .env 与私有域名硬编码）。

相关文档：README.md（速览）· DEPLOY.md（简版勾选，与本文 附录 C 同步）· 本文（详解）。

6. 前置条件

按顺序确认：

1. 腾讯云账号已开通 EdgeOne Pages，可创建 Pages 项目与 KV 命名空间
2. 对象存储账号就绪（七牛和/或 S3 兼容），并有权限改 CORS、绑域名
3. 两个自定义域名已（或即将）解析到 EdgeOne，并计划绑定到同一 Pages 项目：
   • 管理：oneypa.xxx
   • 分享：oneyp.xxx
4. CNB 仓库推送权限；Secret 中已有 EDGEONE_PAGES_API_TOKEN（或 EDGEONE_API_TOKEN），且对本仓库 imports 授权
5. 本地调试需要 Node.js ≥ 18（推荐与 CI 一致的 Node 20）
6. （可选）钉钉机器人 SECRET / WEBHOOK，用于部署完成通知

7. 部署步骤（详细）

建议按 A → B → C → D → E → F 顺序完成。首次上线约 30–60 分钟（含域名生效时间）。

步骤 A：准备 CNB 仓库

1. 确认远程仓库存在：https://cnb.cool/onedayxyy/oneyp
   • 若尚未创建，参考 CREATE_CNB_REPO.md：

1cd /d/oneyp
2git remote add origin https://cnb.cool/onedayxyy/oneyp.git
3git push -u origin master

2. 打开 Secret 仓库：https://cnb.cool/onedayxyy/secret/-/blob/main/envs.yml
3. 确保其中至少包含（值勿提交进业务仓库）：
   • EDGEONE_PAGES_API_TOKEN（或兼容名 EDGEONE_API_TOKEN）
   • （可选）钉钉 SECRET、WEBHOOK
4. 在 Secret 侧为本仓库 onedayxyy/oneyp 授权可读（否则 .cnb.yml 的 imports 拿不到 Token，部署阶段会直接失败并打印中文错误提示）。

步骤 B：配置对象存储（以七牛为例）

S3 兼容可跳过 B 中七牛特有项，改在上线后用后台「设置」配置（见步骤 F）。冷启动仍建议至少能让管理端登录，再在 UI 里配存储。

1. 创建 / 选择桶

   • 建议专用桶（示例名 oneeoyp）；也可用现有桶 + 对象前缀 drive/

2. 访问控制

   • 建议私有桶；环境变量或配置中 QINIU_PRIVATE=true
   • 私有桶务必确认：绑定的媒体域名支持私有下载 / 签名访问（七牛控制台域名详情或「私有空间」相关选项）。
     域名已绑定但未开私有签名时，直链或签名 URL 可能 401/403，表现为能列目录、预览失败。
     （应用侧也会走同源 /api/.../media 代理；域名签名能力仍建议打开，避免个别直链场景失败。）

3. 绑定媒体域名

   • 在桶「域名管理」绑定域名（如当前常用：oneypqn.onedayxyy.cn）
   • 填入 QINIU_DOMAIN 时必须是该列表里已绑定的域名
   • 反例：自行臆造或尚未绑定的域名（如历史上的 oneypcdn.onedayxyy.cn 未绑定时）→ 七牛返回 no such domain，预览裂图
   • 可用 /api/setup/status 的 bucketDomains / domainBound 核对配置域名是否真在桶上

4. 配置 CORS（浏览器直传必需）

   项	建议值
   允许源	https://oneypa.onedayxyy.cn、本地 http://127.0.0.1:8090 等
   Method	至少 GET / POST / PUT / HEAD / OPTIONS
   Header	*
   视情况	分享域若需浏览器直连存储，也一并加入

5. 拿到密钥

   • AccessKey → 稍后填 QINIU_AK
   • SecretKey → 稍后填 QINIU_SK
   • 也可不在环境变量写密钥，上线后仅在管理后台「设置」填写（写入 KV storage:config）

S3 兼容补充要点（阿里云 OSS / 腾讯云 COS / MinIO 等）：

• Endpoint、Region、Bucket、AK/SK 必填
• MinIO 建议开启 Path-Style
• 同样配置 CORS（S3 直传为 PUT）
• 私有桶预览走同源 media 代理；公有访问域名可选
• 无七牛 vframe：视频封面多为占位图

步骤 C：创建并配置 EdgeOne Pages

1. 登录腾讯云 EdgeOne Pages，创建项目，名称建议与仓库一致：oneyp（与 edgeone.json 的 name、.cnb.yml 中 -n oneyp 一致）。
2. 创建 KV 命名空间，并绑定到该 Pages 项目：
   • 绑定变量名必须为：ADMIN_KV（大小写一致）
   • 分享创建、存储保存、登录 / 分享密码限流都依赖此绑定；名称错误会导致 503 或功能半残。
3. 在 Pages 控制台配置环境变量（至少必填项）：

完整变量见 第 13 节。本地模板见 .env.example。

4. 绑定自定义域名（两个都绑到同一个项目 oneyp）：
   • oneypa.onedayxyy.cn → 管理
   • oneyp.onedayxyy.cn → 分享
5. 确认项目 输出目录 为 public（仓库内 edgeone.json 已写 outputDirectory: "public"）。
6. （可选）在控制台先做一次手动部署验证；日常以 CNB 自动部署为准。

步骤 D：确认仓库内部署配置文件

部署前在本地确认以下文件存在且内容合理：

.cnb.yml 触发条件（ifModify）：仅当以下路径有变更时才部署：

• functions/**
• public/**
• scripts/**
• edgeone.json
• .cnb.yml

流水线实质步骤：

1. node scripts/write-version.mjs → 写入 public/version.json 与 functions/lib/version.js
2. npm install -g edgeone@${EDGEONE_CLI_VERSION}（默认版本 1）
3. edgeone makers deploy . -n oneyp -t "$TOKEN"
4. （可选）钉钉通知：「OneYP」云盘部署完成 + 耗时

步骤 E：推送代码触发自动部署

1cd /d/oneyp
2# 确认改动会命中 ifModify 路径，否则不会部署
3git status
4git add -A
5git commit -m "feat: 你的中文说明"
6git push origin master

提交信息约定：中文描述 + 保留 feat / fix / chore 等前缀（见 .cursor/rules/commit-messages.mdc），例如：feat: 完善部署文档与冒烟清单。

部署后自检：

1. 打开 CNB 流水线日志，确认 Token 非空、edgeone makers deploy 成功
2. 浏览器访问：
   • https://oneypa.onedayxyy.cn — 应出现登录页
   • https://oneyp.onedayxyy.cn — 应出现分享门户提示页
3. 可选：https://oneypa.onedayxyy.cn/api/health、/api/setup/status 查看 JSON 就绪字段

若未触发部署：检查 push 是否改到监控路径；检查 Secret imports；检查分支是否为 master。

步骤 F：上线后首次配置（管理后台）

1. 打开 https://oneypa.onedayxyy.cn，使用 ADMIN_PASSWORD 登录。
2. 进入 设置：
   • 查看「当前启用」存储摘要与系统诊断（/api/setup/status）
   • 若冷启动未配齐存储：添加存储（七牛或 S3）→ 测试连接 → 保存 → 设为启用
3. 确认诊断中大致满足：jwt / password / kv 为就绪；storage.ready 为 true；七牛场景下 domainBound 尽量为 true。
4. 上传一张小图做预览验证，再创建一条分享，用分享域打开 /s/{id}。
5. 完整勾选见 第 10 节冒烟清单。

S3 在后台填写的字段对照：

注意：同一时间只启用一套；切换存储不会自动迁移旧文件。

8. 本地开发

1cd /d/oneyp
2cp .env.example .env
3# 编辑 .env：填入 ADMIN_PASSWORD、JWT_SECRET，以及可选 QINIU_*
4node scripts/local-server.mjs

可选本地变量：PORT（默认 8090）、HOST（默认 127.0.0.1）。

说明：

• 本地使用内存版 KV，进程重启后分享记录、存储配置、限流状态会丢失（除非你自行做持久化改造）。
• 直传对象存储时，请在桶 CORS 中加入本地源 http://127.0.0.1:8090。
• 缺少关键环境变量时，本地服务启动可能会打印告警，但仍可先改前端；调存储相关功能需补齐密钥。

9. 管理后台使用要点

9.1 登录

打开管理域，输入 ADMIN_PASSWORD。登录失败次数过多会触发递增锁定（依赖 KV）：约 6 / 9 / 12 / … 次失败后锁定 1 分钟 → 3 分钟 → … → 最长约 24 小时。

9.2 存储设置（重要）

1. 查看「当前启用」摘要
2. 添加存储 → 测试连接 → 保存
3. 设为启用
4. 之后文件列表 / 上传 / 预览 / 分享媒体均走当前启用后端

密钥在接口响应中脱敏；编辑时 Secret 留空表示不修改。

9.3 文件与分享

• 上传区支持拖拽；大文件优先浏览器直传
• 可新建目录、网格 / 列表切换、文件夹拖拽排序
• 「分享」可设密码、过期小时、自定义 slug（如 /s/oneblog）
• 分享管理可复制链接、撤销

10. 冒烟验收清单

部署或大改后建议逐项勾选：

• oneypa 可打开登录页并成功登录
• /api/health 返回 service: oneyp 与版本号
• 「设置」中系统诊断：kv 就绪；storage.ready 为 true
• 存储「测试连接」成功，且已设为启用
• 七牛：QINIU_DOMAIN / 配置域名在 bucketDomains 中，domainBound 为真
• 上传图片 → 网格 / 列表可见 → 预览正常
• 上传短视频 → 可播放（七牛可有封面；S3 封面可为占位）
• 创建分享 → https://oneyp.onedayxyy.cn/s/{id} 可打开
• 加密分享：未输密码不可列目录；输对密码后可预览
• 删除文件 / 目录行为正常
• 推送命中监控路径后 CNB 自动部署成功（可选看钉钉通知）

11. 存在问题与已知限制

以下为当前版本已知限制与待办，部署与排障时请知情预期：

12. 常见问题

预览裂图 / no such domain

QINIU_DOMAIN（或后台配置的域名）填了未在桶「域名管理」绑定的域名。

• 典型反例：配置了 oneypcdn.onedayxyy.cn，但桶上实际只绑了 oneypqn.onedayxyy.cn（或尚未完成绑定）→ 七牛返回 no such domain，图片/视频裂图。
• 处理：到七牛桶域名管理核对已绑定列表，把配置改成列表中的域名；或用 /api/setup/status 看 bucketDomains / domainBound。

私有桶能列出文件，但预览 401/403 / 无法播放

绑定域名后仍失败时，检查该域名是否开启私有下载 / 签名访问（与 QINIU_PRIVATE=true 配套）。未开签名时，带 token 的媒体 URL 可能被拒。也可先依赖同源 /api/drive/media 或 /api/s/{id}/media 代理验证文件本身是否可读，再回头修域名侧私有访问。

直传失败 / CORS

给对象存储配置 CORS，允许管理域（及本地调试源）。七牛直传多为 POST 表单，S3 直传为 PUT。

登录提示未配置 JWT / 密码

Pages 环境变量缺少 JWT_SECRET 或 ADMIN_PASSWORD（或未配置可用的 KV 回退）。改完环境变量后需等待 / 重新部署使边缘生效。

切换存储后旧文件不见了

预期行为：文件实体在原桶 / 前缀下，不会自动迁移。切回原存储即可看到。

部署未触发

检查：是否 push 到 master；变更是否落在 ifModify 路径；CNB 是否成功 imports 到 Token；流水线日志是否报「缺少 EDGEONE_PAGES_API_TOKEN」。

KV 不可用

确认 Pages 绑定名称恰为 ADMIN_KV。分享创建、存储保存、限流都依赖它。

分享链接域名不对

检查 SHARE_PUBLIC_ORIGIN（或别名 PUBLIC_SHARE_ORIGIN）是否为分享域完整 origin（含 https://，无多余路径）。

管理域与分享域行为反了

确认两个域名都绑到同一项目，且 Host 命名符合分流规则（管理域含 oneypa，分享域为 oneyp. 前缀且不是 oneypa）。

13. 环境变量完整说明

13.1 EdgeOne Pages / 生产（与 .env.example 对齐）

*也可写入 KV 作为回退：JWT_SECRET、ADMIN_PASSWORD（以及可选 ADMIN_PASSWORD_HASH）。

13.2 支持但未写入 .env.example 的变量

13.3 仅本地

13.4 仅 CNB CI（Secret envs.yml）

存储解析优先级：KV storage:config 中启用的后端 → 否则环境变量 / KV 中的 QINIU_*（虚拟 id env-qiniu）→ 否则报未配置。

14. 关键文件索引

15. 安全建议

1. 永远不要把 .env、真实 AK/SK、Pages Token 提交进 Git
2. 生产使用强随机 JWT_SECRET 与足够强度的 ADMIN_PASSWORD（或改用 ADMIN_PASSWORD_HASH）
3. 优先私有桶 + 同源媒体代理；公有桶需自行评估盗链与流量风险
4. 开源对外副本务必去掉私有域名默认值与 Secret 引用
5. 定期轮换对象存储密钥与管理员密码
6. 分享链接视为能力凭证：设置合理过期与密码；重要文件避免长期无密码公开
7. CNB Secret 仅授权必要仓库读取，避免 Token 扩散

16. 版本与维护

• 应用版本格式：{年}.{月}.{日}-{commit前6位}（Asia/Shanghai），由 scripts/write-version.mjs 在 CI 写入
• 浏览器可读 public/version.json；Functions 使用 functions/lib/version.js 中的 APP_VERSION
• edgeone.json 内 "version": "1.0.0" 为 Pages 项目元数据，不等于应用构建版本
• 功能迭代以 master 为准；提交信息使用中文并保留 conventional 前缀
• 本文档随架构变更请同步更新正文「文档更新日期」，并视需要调整文件名中的日期

附录 A：主要 API 一览（便于联调）

附录 B：推荐首次部署时间线

1Day 0
2  ├─ A. CNB 仓库 + Secret 授权
3  ├─ B. 对象存储桶 + 域名 + CORS
4  ├─ C. EdgeOne Pages + KV + 环境变量 + 双域名
5  ├─ E. push master 自动部署
6  └─ F. 登录 → 启用存储 → 冒烟清单全勾选
7
8日常迭代
9  └─ 改 functions/public/scripts/edgeone.json/.cnb.yml → push master → 看流水线与钉钉

附录 C：与 DEPLOY.md 对齐的勾选清单

与仓库根目录 DEPLOY.md 同结构，便于在完整文档内一次勾完；任一侧变更时请两边同步。

C.1 七牛

• 桶（建议新桶 oneeoyp，也可暂用现有桶 + drive/ 前缀）
• 访问控制：建议私有；QINIU_PRIVATE=true
• 私有桶：绑定域名已开启私有下载 / 签名访问
• CDN/源站域名：必须是桶「域名管理」里已绑定的域名（示例：oneypqn.onedayxyy.cn）→ QINIU_DOMAIN
• 勿填未绑定域名（反例：oneypcdn 未绑定时 → no such domain，预览裂图）
• CORS：允许 https://oneypa.onedayxyy.cn、本地调试源；Method 含 GET/POST/PUT 等；Header *

C.2 EdgeOne Pages

• 项目名：oneyp
• KV 绑定：ADMIN_KV
• 环境变量：对齐 .env.example / 本文第 13 节
• 域名：oneypa.onedayxyy.cn（管理）、oneyp.onedayxyy.cn（分享）
• SHARE_PUBLIC_ORIGIN=https://oneyp.onedayxyy.cn

C.3 CNB

• 仓库：https://cnb.cool/onedayxyy/oneyp
• envs.yml 对本仓库授权 EDGEONE_PAGES_API_TOKEN
• push master 触发部署

C.4 冒烟

• 打开 oneypa → 登录
• 设置 / 诊断页：存储测试通过并已启用
• 上传图片/短视频 → 预览正常
• 分享目录 → oneyp /s/{id} 可预览
• 加密分享需密码

更细的验收项见本文 第 10 节。项目速览见 README.md。

文档结束。若线上域名、桶名或 Secret 路径有变更，请优先改本文件第 5 节对照表、附录 C 与 DEPLOY.md，避免后人照抄过期值。