ApuOS 社区

帖子

• ---

  官方规范、Schema与模板下载导航
  A apuos-admin

  官方规范与模板 社区指南

  官方材料集中入口

  完整套件开发规范目录将截图里的规范按任务整理，并提供原始文件和模板下载。请先核对版本与状态：当前官方应用35项（18默认/17可选），原始复核/迁移材料中的33项属于历史版本，原文保留供审核追溯。

  • 官方应用规范复核：历史复核与规则依据。
  • 官方平台模块1.1合同：入口、宿主版本、安装预览/确认、权限与数据保留。
  • SPKG格式与签名：目录、尾部、摘要、归档模式和生命周期。
  • Manifest字段与Schema：共同字段、格式分支、双架构模板及机器校验。
  • 仓库索引、审核与发布：签名索引、不可变发布与未来后台合同。
  • 文档格式和交付验收：README、CHANGELOG、接口文档、运维与验证材料。
  • 下载全部规范、Schema和示例ZIP。

  文档与格式要求

  README记录当前用途/配置/运行和限制，CHANGELOG逐版记录；Manifest与JSON Schema严格一致，禁止未知字段与重复键。接口说明应写清认证、参数类型和单位、响应、错误、状态及重试；测试材料需对应准确提交、版本、包哈希和真实环境。

  社区帖子使用Markdown，官网Wiki使用DokuWiki原生标题/链接/表格/代码块。下载的规范保持原文，SOURCE.json提供来源提交与文件摘要。不能把格式校验当作安全扫描通过，也不能把原生执行器或/admin/v1规划接口写成已经上线。

  如何反馈规范问题

  请写明文件名、条款/字段、对应版本、当前例子、预期修改及兼容影响。代码和模板讨论留在本板块，可复现的工具/平台缺陷关联Bug主题；生产签名密钥、有效凭据与业务数据始终不进入公开帖子。

• ---

  SPKG封装方法：目录、Manifest、签名与校验
  A apuos-admin

  套件开发与封装 社区指南

  从这里开始封装套件

  正式格式名称是 SPKG（.spkg）。SPKG1.0用于第三方原生程序格式合同，SPKG1.1用于受审定的官方平台模块。官方1.1已有引擎，原生1.0的格式/Schema/工具可用，但第三方生产安装执行器尚未开放。

  1. 先确认格式，按规定根目录放manifest.json和实际架构文件，不加套件名外层目录。
  2. 用Rust spkg工具检查Manifest与目录，输出到源目录之外。
  3. 开发未签名包只有显式allow-unsigned可预检，不能当作生产可信包。
  4. 正式签名使用仓库外0600种子文件，外部受信任公钥验签；不要在社区上传私钥。
  5. 核对整包SHA-256、工具版本、实际架构/ABI、依赖、权限与数据保留，并记录可复现测试。

  命令示例与完整教程

  从目录到签名包的逐步教程给出工具构建、manifest、build、public-key和check命令，以及示例目录和当前限制。
  格式与签名说明尾部、摘要、归档、路径、大小、权限和生命周期合同。
  Manifest与Schema解释字段、必填项、架构、入口和资源约束。

  发帖需要什么

  请按编辑器提纲提供格式版本、工具版本、NAS/硬件架构、最小目录和脱敏Manifest、完整命令/错误码、预期和实际结果。图标和截图引用文件也应核对。不要公开用户数据、令牌、服务器账号或私钥；author字段不授予官方身份。

  社区讨论和工具格式通过不等于审核发布。公开第三方上传/审核后台仍为规划合同，不能把不存在的接口当成已上线能力。官方模块必须与精确宿主版本、受审ID与签名发行流程一致。

• ---

  开发者接入入口与最小联调清单
  A apuos-admin

  开发者与 API 社区指南

  先选择正确的服务边界

  官网客户端开发指南说明云端发现/配对、NAS HTTP 和 WebRTC 直传协议。云端只处理连接协调，文件内容与文件信息不上传到发现服务器。NAS 会话、云端配对 bearer 与旧互传 peer claimToken 不可互换。

  推荐的联调顺序

  1. 查询目标 NAS 的运行版本和 capabilities，核对所需套件、数据卷和实际账号权限。
  2. 先在可信局域网完成登录、目录浏览和隔离文件上传；记录权威received断点与最终receipt。
  3. 再实现签名配对、NAS明确审批、SDP/ICE验证和实际DTLS证书核对，文件走直连通道。
  4. 覆盖断网、过期重新登录、进程重启、错误摘要、同名冲突和提交结果不确定等情况。

  怎样报告接口问题

  提供方法、路径、版本、脱敏后的请求/响应与错误码。请使用合成小文件和最小代码示例，保留关键字段类型、字节数、偏移和时间单位。不要上传真实NAS密码、Bearer、PIN、私钥或用户原始文件。

  新版持久上传接口与早期Flutter单文件原型的能力不同，文档存在不代表旧客户端已经接入。协议描述、便携测试、真实Linux运行、生产账号文件权限与公网NAT条件要分别验证。社区可讨论接口设计和复现过程，确定缺陷后在Bug板块保留独立记录。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  教程发布规范：让别人能够复现你的经验
  A apuos-admin

  教程与经验分享 社区指南

  一篇教程需要包含什么

  建议按“目标、设备与版本、前置条件、步骤、验证、回退”组织内容。先解释要完成什么，再说明实际验证过的环境和需要的权限。命令、配置文件和截图应配合文字说明，读者需要知道每一步改变了什么，以及如何判断它是否成功。

  区分验证结果和推测

  只把自己确实验证过的设备、版本和功能写成已经可用。未测试的系统、浏览器或原生移动平台请明确注明。分享容器和工作流时提供软件版本与公开来源，说明数据目录、端口和调用服务；不要求读者直接复制自己的密码、私钥或有效令牌。

  关注可回退性

  对文件、存储或网络配置有影响的步骤，先讲清备份与恢复方式。测试完成后说明如何删除仅属于测试的资源，避免读者误清理业务文件。引用他人项目或文章时注明来源与许可证，使用个人样例代替敏感业务内容。

  发布后可在原主题持续更新适用版本，其他用户复现时说明自己的环境与结果。发现平台缺陷时创建独立Bug主题并双向链接。浏览全部应用可以找到更多可分享的实际场景。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  安装与硬件问题需要提供哪些信息
  A apuos-admin

  安装与硬件适配 社区指南

  用实际型号和版本讨论适配

  ApuOS 目标面向多种设备，具体安装、驱动和运行能力仍依赖已发布的硬件适配。发帖时提供设备型号、CPU架构、系统与内核版本、启动方式，以及网卡、显示、USB设备或UPS的具体型号；相同品牌不同芯片和连接方式可能具有不同表现。

  安装前后分别记录

  首次安装请说明使用的镜像来源和版本、目标存储设备以及失败发生在哪一步。已有系统升级问题应记录升级前后版本、可回退方式和报错。不要在公开帖子里上传能直接登录机器的凭据，也不要为尝试驱动随意替换内核、固件或设备树。

  外设排查

  USB、串口、网络设备的检查方式不同。说明连接方式、是否被系统识别、何时断开及应用显示的状态；截取与该设备有关的脱敏日志。对于供电、磁盘或UPS相关故障，先确保数据和供电安全，再考虑可逆的检查步骤。

  可参考首次使用和常见问题。社区经验是针对特定环境的记录，不能自动当作所有同类设备已经适配的结论。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  应用安装指南：分清官方应用、套件和容器
  A apuos-admin

  应用、套件与容器 社区指南

  三类入口各自负责什么

  官方应用是 ApuOS 的功能模块，套件中心还管理设备支持的原生软件；应用中心可从目录选择容器应用，容器管理用于查看引擎、镜像、网络与 Compose 项目。请在标题中写清名称和入口，避免把“已经安装模块”与“第三方服务已经配置成功”混为一谈。

  安装与更新排查

  核对设备架构、系统版本、磁盘空间、依赖服务和实际安装结果。第一次拉取镜像或安装依赖可能受网络影响；需要提供完整错误码和脱敏日志。先确认端口与数据目录映射，再开放相应入口。不要把整个主机根目录或可用密钥映射到不受信任的容器。

  保留业务数据

  更新或重建前检查应用自己的备份方式和数据卷。停止服务、卸载界面、删除容器和清理持久数据是不同动作，不能把其中一个当作另一个。讨论步骤时注明哪些操作可回退、哪些会改变数据，优先使用隔离测试项目。

  可先阅读全部应用指南、套件中心与应用中心和容器。涉及平台缺陷时按 Issue 模板提供最小复现。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  存储与备份：先确认数据，再进行操作
  A apuos-admin

  存储、备份与恢复 社区指南

  讨论范围

  这里交流磁盘识别、存储池、共享目录、快照、设备同步、NAS 对外备份与文件恢复。请说明正在配置新磁盘，还是处理已有业务数据；给出文件系统、容量、挂载和任务状态，设备序列号及真实目录名称需要脱敏。

  操作前的检查

  涉及格式化、重建、清理、删除或恢复覆盖时，先确认目标设备和已验证的副本。RAID 与快照各有作用，不能直接替代异地备份。不要仅凭一张容量截图执行他人提供的破坏性命令；有重要文件时保留原件和错误信息，先讨论可回退的检查方法。

  怎样描述备份问题

  说明是设备上传至 NAS、NAS 备份至另一位置，还是云端连接任务。记录任务模式、源/目标类型、实际进度、错误码及是否发生服务重启。完成记录不代表已经验证可恢复；建议在隔离目录进行抽样恢复，再核对文件内容。

  基础说明见存储管理、共享文件夹和备份与恢复。如果发现可复现缺陷，请在 Bug 板块建立主题并关联本次讨论。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  设备同步排查：从配对到文件落盘
  A apuos-admin

  客户端与设备同步 社区指南

  先确认是哪一条连接

  ApuSync 的云端服务用于设备发现、配对与签名信令；文件内容通过 APP 与 NAS 的直连传输。ApuConnect 是另一条远程访问路径，请在主题里说明你使用的具体入口，不要把两种连接的令牌、行为和限制混在一起。

  按阶段提供信息

  配对失败时提供客户端平台/版本、NAS 版本和错误码；审批失败时在 NAS 侧核对本次客户端身份与账号权限。不要贴仍有效的 PIN、私钥或会话令牌。连接成功后无法上传时，检查接收目录、数据卷挂载、文件管理与文件互传套件以及实际用户权限。

  续传与完成状态

  旧版 Flutter 单文件原型不包含新版持久续传和后台相册队列。新版接口区分已接收、校验中和最终提交回执，发送字节达到100%不能直接等同于已备份成功。说明问题时标出具体阶段、文件大小和是否发生重启，不必公开原始个人文件。

  公网 UDP 与 NAT 条件会影响直连，云服务在线不代表所有网络都可穿透。查看设备直传步骤；客户端开发人员可参照接入规范复现最小文件流程。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  AI 能力入门：模型、知识与自动化
  A apuos-admin

  AI 与自主感知 社区指南

  可以在这里交流什么

  AI 大模型、算法商城、AI Agent、AI 硬件、知识库和自动化都可以在本板块讨论。欢迎分享模型接入方法、端侧资源配置、知识检索效果和有边界的自动化流程。ApuOS 的自主感知定位面向实际设备与场景，具体能力以当前版本和配置为准。

  先分清运行方式

  本地推理需要匹配的模型格式、运行引擎、硬件能力和可用内存；云端模型需要有效服务地址与凭据。模型能够下载不代表设备可以运行它，也不能仅凭网络通畅推断调用额度和服务权限可用。发帖请写明模型标识、运行方式、设备内存以及脱敏错误码。

  知识与自动化

  讨论知识检索时说明文件类型、索引进度、查询示例与预期效果，尽量用可公开的最小样例。分享工作流时标明输入、输出、调用服务及是否会修改文件或发送消息，先用隔离数据验证。不要公开 API Key、用户对话或私有知识内容。

  可从AI 使用手册与官网 AI 能力了解当前入口。确定可复现的产品缺陷应另建 Bug 主题，并从这里关联过去。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。

• ---

  怎样提交一条可讨论的功能建议
  A apuos-admin

  功能建议 社区指南

  从场景和目标开始

  请说明谁在什么设备、什么环境中需要完成什么任务，以及当前操作为什么不够用。例如“家里的平板希望在夜间连接电源时备份新增照片”，比“增加同步”更容易判断具体范围。可以附流程草图、公开参考链接或已经脱敏的界面截图。

  建议包含的内容

  使用编辑器提纲，写清当前限制、预期行为、现有替代方案和适用设备。说明功能是否涉及数据删除、长期后台运行、第三方账号或额外硬件，这会影响实现方式与验证范围。尽量一帖一个主要建议；已有相似讨论时追加具体场景，避免重复开帖。

  如何讨论和跟进

  其他用户可回复自己的实际需求与约束，也可以通过论坛的收藏、关注或投票功能表达兴趣。维护者会根据实际情况补充可行性与范围，讨论热度不等同于已经承诺排期。请以原主题中的明确回复为准，不将想法或参考图当作已发布能力。

  现有功能可先查看全部应用指南与官网功能介绍。若实际行为与已经公开的功能不一致，请按 Bug 与 Issue 模板提交复现信息。

  发布前检查

  请先搜索已有主题，一帖讨论一个主要问题。截图和日志请遮蔽密码、访问令牌、配对码、许可证私钥、个人文件和设备序列号。社区账号独立于 NAS 账号。涉及存储操作时先备份重要数据，按照实际设备与版本核对说明。