VelaShell 插件市场(velashell-markets)

VelaShell 插件的上传、审核、检索与分发。用户经独立仓库 velashell-identity 的统一认证服务 (OIDC / OpenIddict + MongoDB)登录,上传的 .vpx 先进隔离区, 通过容器校验、结构检查与病毒扫描后才会发布。

上传 ──▶ 隔离桶(vpx-quarantine)──▶ 静态检查 ──▶ ClamAV ──┬─ 通过 ──▶ 正式桶(vpx-public)──▶ 可下载
          ↑ 永不对外可读                                    ├─ 可疑 ──▶ 留隔离区,转人工复核
          └────────────────────────────────────────────────┴─ 有害 ──▶ 留隔离区,拒收并给出原因

快速开始

cp .env.example .env      # 至少改掉 MONGO_ROOT_PASSWORD

# ⚠️ 统一认证服务已拆到独立仓库(2026-08-30)。先在 velashell-identity 里 `docker compose up -d`,
#    否则登录会失败 —— 本仓库不再自带它。

# 起全套,并播三个演示插件 —— 它们会**真的走一遍检测流水线**后才出现在首页
$env:SEED_DEMO_DATA='true'
$env:ASPNETCORE_ENVIRONMENT='Development'
# 先出镜像。api 的镜像由 .NET SDK 直接产出(仓库里没有 api 的 Dockerfile),
# web 仍是 nginx + dist,两个都由这个脚本管。
pwsh ./build/Publish-Images.ps1

docker compose up -d

api 的镜像不再由 compose 构建 —— 改了后端代码之后要先 pwsh ./build/Publish-Images.ps1 -Service api,docker compose up -d 不会替你重新构建。 镜像名、基础镜像、非 root 用户与暴露端口只写在 src/VelaShell.Market.Api/VelaShell.Market.Api.csproj 的「容器」段里。 搬运与推仓库(Harbor)见 docs/images.md。

浏览、搜索、看详情不需要登录;上传、评价、审核要登录。第一次进来先去 http://localhost:7020/account/register 注册一个账号,登录后那一页会显示你的 sub —— 把它填进 .env 的 MODERATOR_SUBJECT 就能进审核台。 完整部署说明(含生产要改的项与常见故障)见 docs/deployment.md。

服务	地址	说明
前端	http://localhost:8000	React + Umi Max + Ant Design Pro
统一认证	http://localhost:7020	在 velashell-identity 仓库,需单独起
API	http://localhost:8080	Swagger 在 Development 下于 /swagger
MinIO 控制台	http://localhost:9001	默认 minioadmin / minioadmin
MongoDB	localhost:27017 / 27018 / 27019	副本集 rs0(主 / 从 / 仲裁)。库名 velashell-market,已启用鉴权;客户端连接认证库填 admin。认证服务的 velashell-identity 库现在归它自己的仓库管
clamd	localhost:3310	首次启动要拉病毒库,约几分钟

ClamAV 病毒库没就绪时 clamd 不接受连接。这时上传的包会停在隔离区等重试, 而不会被当成"干净"放行 —— 引擎不可用绝不等于通过。

本机开发

dotnet run --project src/VelaShell.Market.Api      # API
cd src/VelaShell.Market.Web && bun install && bun run dev   # 前端(代理到 8080)

.vpx 解析用的是 NuGet 上的 VelaShell.PluginSdk(版本钉在 Directory.Packages.props)。 早先"同级目录有 VelaShell 仓库就改引用本地工程"的那个开关已经没有了 —— 于是 宿主机构建与容器构建拿到的是同一个包,这在 api 改用 SDK 容器发布(镜像在宿主机上编译) 之后尤其要紧:那条路本来最容易把本机的临时改动烤进镜像。

前端用 bun,仓库里只有 bun.lock,没有 package-lock.json。前端不在容器里打包: build/web.Dockerfile 只把 dist/ 装进 nginx 镜像,所以在没跑过打包的机器上 构建 web 镜像之前,要先 cd src/VelaShell.Market.Web && bun install && bun run build。 VS 里不用管 —— Web 项目参与解决方案构建时会自己跑 bun install 与 bun run build。

结构

src/
├── VelaShell.Market.Domain/          插件 / 版本 / 评价 / 扫描报告与状态机
├── VelaShell.Market.Infrastructure/  Mongo 上下文与索引、S3 存储、ClamAV、检测流水线
├── VelaShell.Market.Api/             HTTP API(最小 API)、OIDC 资源服务器、Markdown 渲染
└── VelaShell.Market.Web/             前端(Umi Max + Ant Design Pro,详见其 AGENTS.md)
    ├── config/                    路由即菜单、代理、ProLayout 默认外观
    ├── types/                     按服务域拆的全局 .d.ts:MarketAPI / MeAPI / ReviewsAPI / …
    ├── public/scripts/loading.js  首屏占位,会读主题,暗色下不闪白
    ├── src/app.tsx                根主题、全局初始状态(当前用户)、ProLayout 运行时配置
    ├── src/access.ts              权限(signedIn / canModerate),审核台入口据此显隐
    ├── src/configs/               应用常量:分页、排序项、状态到标签的映射、storage key
    ├── src/utils/                 theme(深浅色存储)、auth(OIDC)、format、request
    ├── src/hooks/                 跨页面复用的状态机(分页表格)
    ├── src/services/              按域划分的接口层:market / reviews / me / uploads / moderation
    ├── src/components/            主题(Provider / Sync / Switch)、插件图标、签名与状态标签、检测报告
    └── src/pages/                 浏览 / 详情 / 发布 / 我的上传 / 我的插件 / 审核台
tests/VelaShell.Market.Tests/         静态检测器的地面真值用例
build/                                Dockerfile 与 SDK 同步脚本
docs/                                 架构、安全流水线、身份对接

技术选型

关注点	选择	理由
业务数据	MongoDB(EasilyNET.Mongo 的 MongoContext)	插件元数据是文档形态;三条唯一性不变量由唯一索引而非应用层保证
包存储	S3 协议(部署用 MinIO)	换 AWS S3 / OSS / COS 只改配置;隔离与正式物理分桶
身份	自建 OIDC(OpenIddict + MongoDB)	授权码 + 强制 PKCE;市场 API 只做资源服务器,验 JWT / JWKS,不碰账号与口令
.vpx 解析	VelaShell.PluginSdk	与宿主同一份实现,杜绝"市场收得下、宿主装不上"
病毒扫描	ClamAV(clamd INSTREAM)	独立容器,可换;连不上按"检测未完成"处理
Markdown	Markdig(关 HTML 直通 + 白名单清洗)	只存原文,渲染在读取时做

文档

• 部署
• 架构与数据模型
• 安全检测流水线
• API 一览
• 统一认证(OIDC)