diff --git a/astro.config.mjs b/astro.config.mjs index 01720e2..39eead1 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -4,14 +4,12 @@ import starlight from "@astrojs/starlight"; // https://astro.build/config export default defineConfig({ - site: 'https://kb.solsynth.dev', + site: "https://kb.solsynth.dev", integrations: [ starlight({ title: "Suki", description: - "Solsynth's products kownledge base, including Solar Network, GoatCraft and more.", - defaultLocale: "zh-cn", - locales: { + "Solsynth's products kownledge base, including Solar Network, GoatCraft and more.", defaultLocale: "zh-cn", locales: { en: { label: "English", }, @@ -30,7 +28,44 @@ export default defineConfig({ sidebar: [ { label: "Solar Network", - autogenerate: { directory: "solar-network" }, + items: [ + { + label: "Getting Started", + link: "solar-network", + translations: { "zh-CN": "快速开始" }, + }, + { + label: "Solarpass", + link: "solar-network/account", + translations: { "zh-CN": "太阳通行证" }, + }, + { + label: "Publish & Publishers", + link: "solar-network/publisher", + translations: { "zh-CN": "发布者和发布内容" }, + }, + { + label: "Stickers & Pack", + link: "solar-network/sticker", + translations: { "zh-CN": "贴图与贴图包" }, + }, + { + label: "Wallet", + link: "solar-network/wallet", + translations: { "zh-CN": "源点钱包" }, + }, + { + label: "Stellar Program", + link: "solar-network/stellar-program", + translations: { "zh-CN": "恒星计划" }, + }, + { + label: "Open Platform", + autogenerate: { directory: "solar-network/developers" }, + translations: { "zh-CN": "开放平台" }, + collapsed: true, + }, + ], }, { label: "GoatCraft", @@ -39,6 +74,7 @@ export default defineConfig({ { label: "Solsynth Works", autogenerate: { directory: "standards" }, + translations: { "zh-cn": "标准" }, }, ], }), diff --git a/src/content/docs/zh-cn/solar-network/account.mdx b/src/content/docs/zh-cn/solar-network/account.mdx new file mode 100644 index 0000000..f38b87c --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/account.mdx @@ -0,0 +1,56 @@ +--- +title: Solarpass +--- + +import { Aside } from "@astrojs/starlight/components"; + +Solar Network 上的帐号又称为 Solarpass，其可以在所有 Solsynth 的产品中使用。 + + + +## 创建帐号 + +您可以在 Solian 中创建帐号，创建一个帐号需要您提供以下信息： + +- 帐号名称：帐号名称可以是英文字母、数字、下划线和连字符。 + 并保持全局唯一。**帐号名称在创建之后除特殊情况联系客户支持服务外不可修改** +- 显示名称：帐号显示名称并无太多限制，任意取 4-32 位字符即可。 +- 邮箱：请提供真实有效的邮箱，后续需要接受相关的确认注册邮件。 + 为落实用户协议中的禁止注册子帐号的政策，这项邮箱必须为全局唯一。 +- 密码：后续用来登陆的账号密码。请确保其安全。 + +在注册帐号之后，您需要在您绑定邮件的收件箱中收取一个来自 Solarpass 服务的邮件， +其中包含一个确认注册的连接。在您使用其连接确认注册之前，您的帐号会缺少权限， +导致大部份功能无法使用，其产生的报错是正常情况，请勿回报。 + +### 登陆帐号 + +Solar Network 采用自主研发的多因素验证系统，相比传统的两部验证更加方便，您可以任意挑选您方便的验证因素来登陆。 + +## 删除帐户 + +您可能想要删除您的 Solarpass 帐户，因为您不再需要它了。这里分为两个章节 + +- 删除帐户时要知道的影响 +- 如何删除我的帐户 + +### 删除帐户的注意事项 + +1. 您账户下的发布者将会被删除，包括其创建的帖子、贴图等 +2. 您将无法登录您的帐户 +3. 数据删除将会延迟处理，最高延迟 48 小时。 + +### 如何删除帐户 + +1. 点击「帐户」 +2. 往下翻，找到「账户设置」 +3. 点击「删除帐户」 +4. 服务器会向您绑定的主要邮箱发送一封确认删除的邮件， + 你需要在有效期内确认删除。 diff --git a/src/content/docs/zh-cn/solar-network/developers/file-upload.mdx b/src/content/docs/zh-cn/solar-network/developers/file-upload.mdx new file mode 100644 index 0000000..bd8672c --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/developers/file-upload.mdx @@ -0,0 +1,101 @@ +--- +title: 文件上传 +description: 了解如何使用 Solar Network 的 API 来完成文件上传。 +--- + +在通过网关访问时，需要将 `/api` 替换成服务 ID `/drive`。 + +原有的 `/api/tus` 接口已经过时，即将迎来移除的命运。还请使用新的 Solar Network Multipart Upload 协议上传文件。 + +本文档概述了使用多部分上传 API 分块上传大文件的过程。 + +## 1. 创建上传任务 + +要开始文件上传，您首先需要创建一个上传任务。这是通过向 `/api/files/upload/create` 端点发送 `POST` 请求来完成的。 + +**端点：** `POST /api/files/upload/create` + +**请求体：** + +```json +{ + "hash": "string (文件哈希，例如 MD5 或 SHA256)", + "file_name": "string", + "file_size": "long (字节数)", + "content_type": "string (例如 'image/jpeg')", + "pool_id": "string (GUID，可选)", + "bundle_id": "string (GUID，可选)", + "encrypt_password": "string (可选)", + "expired_at": "string (ISO 8601 格式，可选)", + "chunk_size": "long (字节数，可选，默认 5MB)" +} +``` + +**响应：** + +如果具有相同哈希的文件已存在，服务器将返回 `200 OK`，响应体如下： + +```json +{ + "file_exists": true, + "file": { ... (CloudFile 对象，以 snake_case 格式) ... } +} +``` + +如果文件不存在，服务器将返回 `200 OK`，包含任务 ID 和分块信息： + +```json +{ + "file_exists": false, + "task_id": "string", + "chunk_size": "long", + "chunks_count": "int" +} +``` + +您将需要 `task_id`、`chunk_size` 和 `chunks_count` 用于后续步骤。 + +## 2. 上传文件分块 + +一旦您有了 `task_id`，就可以开始分块上传文件。每个分块作为带有 `multipart/form-data` 的 `POST` 请求发送。 + +**端点：** `POST /api/files/upload/chunk/{taskId}/{chunkIndex}` + +- `taskId`：上一步上传任务的 ID。 +- `chunkIndex`：您正在上传的分块的从 0 开始的索引。 + +**请求体：** + +请求体的格式应为 `multipart/form-data`，包含一个名为 `chunk` 的表单字段，其中包含该分块的二进制数据。 + +每个分块的大小应等于"创建上传任务"步骤中返回的 `chunk_size`，除了最后一个分块可能更小。 + +**响应：** + +成功的分块上传将返回 `200 OK`，响应体为空。 + +您应该上传从 `0` 到 `chunks_count - 1` 的所有分块。 + +## 3. 完成上传 + +所有分块成功上传后，您必须发送最终请求以完成上传过程。这将合并所有分块为单个文件并进行处理。 + +**端点：** `POST /api/files/upload/complete/{taskId}` + +- `taskId`：上传任务的 ID。 + +**请求体：** + +请求体应为空。 + +**响应：** + +成功的请求将返回 `200 OK`，包含新上传文件的 `CloudFile` 对象。 + +```json +{ + ... (CloudFile 对象) ... +} +``` + +如果任何分块缺失或合并过程中发生错误，服务器将返回 `400 Bad Request` 以及错误消息。 diff --git a/src/content/docs/zh-cn/solar-network/developers/index.mdx b/src/content/docs/zh-cn/solar-network/developers/index.mdx new file mode 100644 index 0000000..99b3c71 --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/developers/index.mdx @@ -0,0 +1,10 @@ +--- +title: 开发者服务 +description: 了解如何使用 Solar Network 的 API +--- + +本条目下列内容是提供给开发者阅读的，可能需要有一些技术基础才能理解。 + +在开始使用 Solar Netweork 开发之前，请确保您已充分理解并同意 [Solar Network 开发者协议](https://solsynth.dev/terms/solar-network-dev) + +本文只会提及一些需要特殊注意的地方，对于常见的 CRUD 请求请查看我们的自动生成文档 [Solar Network Swagger](https://solian.app/swagger) diff --git a/src/content/docs/zh-cn/solar-network/developers/routing.mdx b/src/content/docs/zh-cn/solar-network/developers/routing.mdx new file mode 100644 index 0000000..45ea48b --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/developers/routing.mdx @@ -0,0 +1,47 @@ +--- +title: 路由及网关 +description: 了解 Solar Network API 路由的方式 +--- + +众所周知，Solar Network 的服务器是一个微服务项目，所以在访问 API 的时候，您需要注意路径的指定。 + +其构造基本为 `//` + +例如，你需要访问推送服务 (DysonNetwork.Ring) 的通知 API。 + +```bash +export BASE_URL="https://api.solian.app" +export SERVICE_ID="ring" +export PATH="/notifications" +echo $BASE_URL/$SERVICE_ID$PATH +# https://api.solian.app/ring/notifications +``` + +## 服务分工 + +目前来说，Solar Network 服务端有四个各司其职的服务。 + +- Pass 负责身份验证（使用 `id` 访问） +- Ring 负责推送和通知 +- Sphere 负责聊天和帖子以及领域相关的功能 +- Develop 负责开发者相关功能 +- Drive 负责文件上传 + +其各服务的服务 ID 即为小写服务名（不包含 DysonNetwork. 前缀） + +## WebSocket + +WebSocket 由推送服务负责，但是不使用 `/ring` 服务 ID 访问，网关直接处理 `/ws` 的请求。 + +WebSocket 的消息都会使用 WebSocketPacket 结构，其结构如下： + +```json +{ + "type": "包类型", + "data": "包数据，可能为任何结构、类型", + "endpoint": "包需要请求的服务，在服务器传来的包不会携带此项；若客户端需要向服务器发送数据包，需要将此项填写为对应服务的 ID 以帮助网关转发此包", + "error_message": "服务器回传包的错误信息" +} +``` + +在访问 WebSocket 网关的时候，有两种授权方式，一种是通用的 `Authorization` 头。但是由于浏览器无法给 WebSocket 设置请求头，从而提供另一种兼容性选择，将访问令牌放置于 `?tk=` 查询参数中。 diff --git a/src/content/docs/zh-cn/solar-network/index.mdx b/src/content/docs/zh-cn/solar-network/index.mdx index 758a858..b601935 100644 --- a/src/content/docs/zh-cn/solar-network/index.mdx +++ b/src/content/docs/zh-cn/solar-network/index.mdx @@ -1,3 +1,29 @@ --- -title: The Solar Network +title: 快速开始 --- + +Solar Network 是 Solsynth 的开源社交网络项目。 +秉持着开放、包容、友善的原则运营。自 2023 年立项，2024 年上线至今已经过去近 2 个年头了。 + +你可以在以下的连接了解到 Solar Network 项目的更多信息： + +- [Solian](https://github.com/Solsynth/Solian) Solar Network 项目的主仓库 +- [Dyson Network](https://github.com/Solsynth/DysonNetwork) Solar Network 项目的服务器侧代码 +- [Capital](https://solsynth.dev/products/solar-network) Solar Network 项目的官方网站 + +### 在你开始之前 + +在你开始使用 Solar Network 之前，这里有些信息小羊觉得你有必要了解： + +- 配置好网络：你假若在使用 Clash 等代理工具以自动分流的方式从中国大陆地区访问 Solar Network，可能出现请求延迟高的问题，这是因为我们的服务器位于香港，可能被分配到了代理节点，建议走直连以获取更好的体验。 +- 包容心：Solar Network 名义上是 Solsynth 制作群的项目，但实际上 Solsynth 也只有一个目前还是学生的成员，因此软件中可能发现诸多设计缺陷，功能缺失以及漏洞和报错。还请多多包容。 +- 阅读英语：尽管 Solar Network 大部份都具有本地化，但是大多数服务器返回的报错都是英语的，您可以使用翻译尝试阅读，或是在文档中查询解决方案。最后再前往官方的聊天频道或者 GitHub 反馈问题。 +- 反馈问题：你可已在我们的的 GitHub 主仓库反馈问题，在创建新 Issue 前请搜索以确保没有其他人已经反馈了相关的问题并且已被解决。 + +### 开始使用 + +Solar Network 的官方客户端支持绝大部分平台， +你可以从 Solsynth 官网的 [Solar Network 产品页](https://solsynth.dev/zh-cn/products/solar-network#download) +了解下载方式。 + +当您下载完成后，您可以继续阅读章节来了解 Solar Network 的帐号系统。 \ No newline at end of file diff --git a/src/content/docs/zh-cn/solar-network/publisher.mdx b/src/content/docs/zh-cn/solar-network/publisher.mdx new file mode 100644 index 0000000..5d872ae --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/publisher.mdx @@ -0,0 +1,65 @@ +--- +title: 发布者和发布内容 +description: 了解在 Solar Network 上发表内容。 +--- + +import { Aside } from "@astrojs/starlight/components" + +发布者是 Solar Network 上大多数公开发表的内容的管理单位， +一个帐号可以拥有 / 加入多个发布者。 + +在 Solar Network 发布任何内容之前，你需要一个发布者身份。 + +## 创建 + +你可以在发布帖子页面点击空白的（在未创建发布者时可用）发布者头像来创建、 +或者通过「帐号」页面前往「创作者中心」创建（桌面端可直接在侧边栏访问「创作者中心」标签） + + + +一个用户可以同时拥有多个发布者，也可以加入不同的发布者共同管理。 + +在创建发布者时，你需要注意以下几点： + +1. 名称 —— 与帐号名称一样，需要全站唯一并且保持 URL-safe，创建后不可更改。 +2. 头像与头图 —— 在创建、编辑发布者的时候，头像与头图的上传并不是上传之后就立刻应用， + 需要点击 “保存更改” 来正式应用。 + +## 个人与组织 + +发布者分为两种类型，一个是「个人」，一个是「组织」。个人和组织发布者都可以邀请他人共同管理。 +其最大的不同是「个人」发布者会在发布者信息缺失的时候（如头像、头图等）使用用户的信息作为回退版本， +而领域则不会。同时「个人」发布者还会显示用户的状态、和认证状态。 + +同时「组织」发布者的头像是特殊的圆角矩形而并非圆形。 +并且「组织」发布者需要隶属于一个「领域」。 + +## 合作 + +自 v3 以来，发布者可以邀请他人共同管理，内设四个默认的权限等级： + +1. 所有者 —— 拥有所有权限 +2. 管理者 —— 拥有编辑者、观察者的所有权限，同时可以邀请新用户共同管理（权限不能高于自身） +3. 编辑者 —— 拥有在这个发布者上发布资源的权限 +4. 观察者 —— 拥有查看这个发布者的内部统计信息的权限 + +## 开发者 + +「开发者」是「发布者」的一种特殊变种，其可以在「开发者门户」创建「发布者」的「开发者身份」， +用来调用 Solar Network 的开放资源。 + +详情请前往「开发者身份」章节查看。 + +## 认证标志 + +如果你有在 Solar Network 被他人冒充的疑虑，或是想发布一些权威信息，亦或是想展示自己的独特性。你可以申请认证标志。 + +> 你需要在申请认证时拥有 “恒星计划” 订阅。否则请求将不会被处理。认证标志在 “恒星计划” 订阅过期后不会消失。 + +申请发布者的认证与申请帐号的验证相同，你需要向 `lily[at]solsynth.dev` 发送邮件说明，客户支持团队会在 7 个工作日之内回复处理。 + +> 您若需要申请官方性质的认证，需要提供一些证明材料。越齐全成功率越高。 + diff --git a/src/content/docs/zh-cn/solar-network/stellar-program.mdx b/src/content/docs/zh-cn/solar-network/stellar-program.mdx new file mode 100644 index 0000000..2220638 --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/stellar-program.mdx @@ -0,0 +1,64 @@ +--- +title: 恒星计划 +description: Solar Network 的营生项目 +--- + +import { Aside } from "@astrojs/starlight/components" + +> *だって僕は星だから Stellar Stellar —— [Stellar Stellar](https://youtu.be/a51VH9BYzZA?si=yuFvOGtfkuU80hwb)* + + + + +Stellar Program 又名恒星计划是 Solar Network 的会员系统， +参与其的成员可以获得一些特殊的福利和权限以访问新功能。 + +## 等级 + +Stellar Program 订阅分为三级，分别是 Stellar, Nova 和 Supernova。 +其对应的翻译为「恒星」、「新星」与「超新星」。*亦或是「恒星」、「恒星+」、「恒星++」* + +每一等级都包含上一等级的全部功能，并有相应的扩充。 + +## Perks + +1. 等级「恒星」 + - 炫酷彩色用户名 + - 抢先体验新功能 + - 1.5x 经验获得增速 +2. 等级「新星」 + - 等级「恒星」的所有功能 + - 优先功能请求 + - 2x 经验获取增速 +3. 等级「超新星」 + - 等级「新星」的所有功能 + - 2.5x 经验获取增速 + - 优先客户服务支持 + - 源码级技术支持 + +## 获得 + +用户有两种方式获得 Stellar Program，**在应用内通过源点购买** 或者 **通过赞助支持 Solar Network 的开发时的赠品**。 + +### 应用内购买 + +应用内通过 Solarpay 来购买需要您提前设置好 PIN Code 以便支付订单。详情请转到「源点钱包」章节。 + +在应用内购买的价格为： + +- 等级「恒星」：每月 1200 源点，需要用户等级达到 30 级 +- 等级「新星」：每月 2400 源点，需要用户等级达到 60 级 +- 等级「超新星」：每月 3600 源点，需要用户等级达到 90 级 + +### 赞助开发时的赠品 + +在通过赞助获得 Stellar Program 之前， +您需要转到帐号设置中连接您要赞助要通过的平台的帐号，以便自动获取订单状态。 + +尽管在回复购买的时候需要提供订单号，但是您仍需要链接对应的帐号来获得 Stellar Program 订阅。 + +您可以通过以下的方式赞助小羊开发 Solar Network，并且获得 Stellar Program 订阅： + + \ No newline at end of file diff --git a/src/content/docs/zh-cn/solar-network/sticker.mdx b/src/content/docs/zh-cn/solar-network/sticker.mdx new file mode 100644 index 0000000..b4e4a59 --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/sticker.mdx @@ -0,0 +1,37 @@ +--- +title: 贴图与贴图包 +description: 了解 Solar Network 上的贴图系统 +--- + +贴图（Stickers）是 Solar Network 上的表情自定表情符号。 +你可以上传图片来创建表情符号， +其可以在几乎所有支持 Markdown 富文本的地方使用。 + +## 创建 + +贴图隶属与贴图包，而贴图包又隶属与发布者，因此你需要一个发布者来创建贴图。 +你可以转到「发布者」章节来了解更多。 + +贴图包支持自定义图标，若不指定图标将会使用第一个贴图来作为贴图包的图标。 + +## 渲染逻辑 + +Solar Network 上的贴图采取自适应大小，若整段文本都只有一个贴图将会使用放大版的贴图， +否则将会使用正常大小的贴图。 + +- 放大版：`80x80` +- 正常版：`20x20` + +因此，你需要上传至少 `80x80` 像素大小的图片来确保其显示清晰。 + +## 使用 + +在 Solian App 中，聊天框左侧提供了一个展开面板，其可以帮助你选择贴图插入到你的消息中。 +对于其他地方，你可以采取手动输入贴图占位符的方式来使用贴图。其格式为 `:prefix+slug:`。 +其中的 `prefix` 为贴图包前缀，而 `slug` 为贴图在创建时设置的别名。 + +在大多数输入框中，在你键入第一个冒号时稍等片刻，Solian 将会启用自动补全来帮助你完成贴图占位符的输入。 + +所有贴图包的贴图不管订阅与否都会在自动补全时显示， +而只有订阅过的贴图包才会在贴图选择器中显示。 +不过订阅与否不影响使用贴图的渲染与否。 \ No newline at end of file diff --git a/src/content/docs/zh-cn/solar-network/wallet.mdx b/src/content/docs/zh-cn/solar-network/wallet.mdx new file mode 100644 index 0000000..04f08d9 --- /dev/null +++ b/src/content/docs/zh-cn/solar-network/wallet.mdx @@ -0,0 +1,79 @@ +--- +title: 源点钱包 +--- + +源能点数（源点）是 Solar Network 上的虚拟币种， +其可以用来支付 Solar Network 上的一些开销。 + +## 钱包 + +您可以在登陆之后在 Solian 中转到「钱包」页面来创建一个源点钱包， +在这之前您不会收到任何被动源点收入。 + +同时您也可以在「钱包」页面查看您当前的余额和交易详情。 + +## 支付 + +在支付之前，为了确保是您本人使用的源点钱包来支付，您需要在「帐号设置」中创建一个 PIN Code 验证因素，其的 Trustworthy（可信度）为 `0`，无法用来登陆。只会用来验证身份。 + +Solian 的客户端在第一次输入 PIN Code 之后会在本地安全的情况下存储加密的 PIN Code，以便提供生物识别快速验证。 + +源点（Source Points aka NSP）是 Solar Network 的基本货币单位，你可以用来购买一些虚拟资源。 + +**注意：Solar Network 的源点不支持储值，任何售卖源点的都是诈骗。** + +## 获得 + +你可以通过每日签到来获得源点。不过在用户创建钱包之前，签到不会奖励任何源点。 + +*下方的内容尚未落地* + +同时，你也可以通过积极的在 Solar Network 上与活动来赚取源点，在达到一定等级之后，你可以加入「创作奖励计划」来在发布帖子、贴图、以及其他内容的时候获得源点奖励。 + +详情还请前往「创作奖励计划」章节查看。 + +*尚未落地的内容段落结束* + +> **你知道吗？** +> 由 Solsynth 运营的 GoatCraft Minecraft 服务器内的货币与源点是互通的，虽然属于 Solar Network 的范围，但是也不失为一种赚取源点的好方式。 + +## 消费 + +> “相比给用户开源，更希望给用户的钱包开洞” —— [@littlesheep](https://solian.app/@littlesheep) 在 ROY 1.5 年国庆时发表的演讲 + +在 Solar Network 上需要源点的消费有很多，下面是一部份： + +- 问 SN 酱问题 +- 奖励帖子 +- 兑换恒星计划 + +## 彩票 + +*因为彩票即属于消费又属于获得，不知道怎么分类之后单独分一类。* + +根据 ROY 2025103001 号决议，发行 Solar Network 01 试验性彩票。 + +玩法说明： + +1. 每天只能购买一次彩票，每注价格为 10 NSP +2. 分为两个区域，数字均不可重复： + - 1 区：选择五个数字 + - 2 区（Bonus）：选择一个数字，若命中则最终奖金基础值 x10 +3. 中奖与否取决于 1 区数字命中几个。若 Bonus 命中但 1 区为命中结果也是 0 NSP +4. 购买时可额外购买 Multiplier，每倍为额外的 10 NSP，会在最终结算时乘上 +5. 每天 UTC 00:00（北京时间 08:00）开奖，若成功中奖会收到交易信息 + +参与方式： + +- 更新到客户端版本 (+138 或以上) 或在网页端 Solian +- 于钱包页面即可看到新增的 Lottery Tab + +> 注意：彩票属于试验性测试阶段，功能未来可能改变，欢迎反馈！ + +## 金点 + +*下方的内容尚未落地* + +金点（Golden Points aka NSD）是 Solar Network 上购买资源时使用的特殊货币。因为目前金点相关的资讯都在小羊脑子里，所以维基暂时介绍不了太多呢…… + +*尚未落地的内容段落结束* diff --git a/src/content/docs/zh-cn/standards/index.mdx b/src/content/docs/zh-cn/standards/index.mdx index c2079e2..9a76f86 100644 --- a/src/content/docs/zh-cn/standards/index.mdx +++ b/src/content/docs/zh-cn/standards/index.mdx @@ -1,5 +1,5 @@ --- -title: 关于 Solsynth Works 标准 +title: 关于标准 description: 了解 Solsynth Works 标准的重要性及其在生态系统中的作用。 ---