¶ CasaOS 开发
Hello！我们非常高兴你有兴趣为 CasaOS 做贡献。在提交你的代码之前，请确保花点时间阅读以下指南。
因为 CasaOS 是一个面向多语种的开源项目，在 GitHub 无论提交 PR 还是 Issue，请尽量用英文描述和交流。这样才能最大化项目的受众面和国际影响力。
¶ 预备知识
- 你应该对 Golang 和脚本开发有一定的熟悉
- 你应该熟悉 Git 和 GitHub 上整个 Pull Request (PR) 流程
¶ Pull Request
- 主分支只是最新稳定版本的一个快照。所有的开发都应该在专门的分支中完成。请不要针对主分支提交 PR。
- 从相关的分支（如 dev ）签出一个主题分支，然后针对该分支进行合并。
- 当你在 PR 上工作时，有多个小的提交是可以的 - GitHub 会在合并前自动将归一。
- 如果添加一个新功能。
- 需要提出这个功能的价值点。理想情况下，你应该先开一个建议条目，并在工作前和小组成员进行充分的讨论。
- 如果修复错误。
- 如果你正在解决一个特殊的问题，在你的 PR 标题中添加
(fix #xxxx[,#xxxx])(#xxxx是问题 ID)，以获得更好的发布日志，例如update entities encoding/decoding（fix #3899）。 - 在 PR 中提供一个详细的错误描述。最好有演示。
- 如果你正在解决一个特殊的问题，在你的 PR 标题中添加
¶ API 接口
- Gateway API (仍未就绪)
- UserService API (仅提供有限的 API)
- LocalStorage API
- AppManagement API
- MessageBus API
¶ 架构
¶ 开发环境搭建
下面的步骤并不是开始搭建 CasaOS 开发的唯一方式，可自由搭配个人经验。
同时所有下载步骤都假设你能访问国际互联网。如果下载有困难，可能寻找并替代相关的镜像源。
¶ Go
-
首先从 https://golang.google.cn/dl/ 下载针对 Linux 的压缩包
-
从压缩包中解压
go目录并移至$HOME/.local/go(或者任何你喜欢的路径) -
确保
~/.profile启动文件中的底部包含下面这一行（如果选择了不同路径，记得替换）PATH="$HOME/.local/go/bin:$HOME/go/bin:$PATH"两个路径区别如下
$HOME/.local/go路径为 Go 的安装目录，包含 Go 的核心文件、文档、库$HOME/go路径为 Go 的工具及依赖目录，包含你的项目将会依赖的三方工具和库
-
运行
go version确保 Go 安装成功
¶ 其它构建和编译工具
-
安装
goreleaser- 负责编译编排及打包go install github.com/goreleaser/goreleaser@latest -
安装 C/C++ 编译工具 - 负责 CGO 依赖的编译，例如 go-sqlite3
因为 CasaOS 是跨架构的项目，所以其他架构（arm64、armhf）的编译器也需要安装，以支持 Raspberry Pi 这些非 x86 架构的设备
sudo apt-get --no-install-recommends install upx \ gcc libc6-dev-amd64-cross \ gcc-aarch64-linux-gnu libc6-dev-arm64-cross \ gcc-arm-linux-gnueabihf libc6-dev-armhf-cross
¶ VSCode
-
首先从官网 https://code.visualstudio.com/ 下载并安装 VSCode
-
然后安装相应插件
- https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck
- https://marketplace.visualstudio.com/items?itemName=golang.Go
- https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi
- https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh
-（如果是从 Windows / Mac 远程访问 Linux 开发环境则需要这个插件）
-
打开 VSCode 的
settings.json配置文件在命令中心（Ctrl-Shift-P）搜索 "
settings.json" 打开配置文件。- 如果是本地开发环境，则打开默认配置文件
- 如果是远程开发环境，则打开远程配置文件
确认配置文件包含如下配置
{ "go.goroot": "~/.local/go", "go.gopath": "~/go" }两个路径区别如下
go.goroot路径为 Go 的安装目录，包含 Go 的核心文件、文档、库go.gopath路径为 Go 的工具及依赖目录，包含你的项目将会依赖的三方工具和库
-
同时建议加入以下可以有效提升代码质量的配置 (非必须 - 如果你更好的配置的话，请分享)
{ "git.autofetch": "all", "go.delveConfig": { "showGlobalVariables": true, }, "go.diagnostic.vulncheck": "Imports", "go.inlayHints.assignVariableTypes": true, "go.inlayHints.compositeLiteralFields": true, "go.inlayHints.compositeLiteralTypes": true, "go.inlayHints.constantValues": true, "go.inlayHints.functionTypeParameters": true, "go.inlayHints.parameterNames": true, "go.inlayHints.rangeVariableTypes": true, "go.lintFlags": [ "-D", "staticcheck", "-E", "gocyclo,gosec,makezero,prealloc,revive,usestdlibvars" ], "go.lintTool": "golangci-lint", "go.lintOnSave": "workspace", "go.toolsManagement.autoUpdate": true, "gopls": { "formatting.gofumpt": true, "ui.diagnostic.analyses": { "fieldalignment": true, "nilness": true, "shadow": true, "unusedparams": true, "unusedvariable": true, "unusedwrite": true, "useany": true, }, "ui.semanticTokens": true, "ui.diagnostic.staticcheck": true, }, }- 访问 https://code.visualstudio.com/docs/languages/go 获得更多 Go 插件配置的细节。
- 访问 https://golangci-lint.run/usage/linters/ 获得更多静态代码分析器的种类（安全、性能、最佳实践）和配置。
- 访问 https://github.com/mvdan/gofumpt - 比 Go 默认的
gofmt更严格的代码格式化工具。
¶ Git
-
安装
gitsudo apt-get --no-install-recommends install git -
克隆以下所有代码仓库
git clone git@github.com:IceWhaleTech/CasaOS-Common.git git clone git@github.com:IceWhaleTech/CasaOS-CLI.git git clone git@github.com:IceWhaleTech/CasaOS-Gateway.git git clone git@github.com:IceWhaleTech/CasaOS-MessageBus.git git clone git@github.com:IceWhaleTech/CasaOS-UserService.git git clone git@github.com:IceWhaleTech/CasaOS-LocalStorage.git git clone git@github.com:IceWhaleTech/CasaOS-AppManagement.git git clone git@github.com:IceWhaleTech/CasaOS.git -
推荐创建一个包含以上所有仓库的 VSCode 工作空间 （非必须）
你可以要么通过 File 菜单一个一个手动加到工作空间里，要么在克隆代码仓库的主目录创建一个
CasaOS.code-workspace文件，包含如下内容$ cat CasaOS.code-workspace { "folders": [ { "path": "CasaOS-Common" }, { "path": "CasaOS-CLI" }, { "path": "CasaOS-Gateway" }, { "path": "CasaOS-MessageBus" }, { "path": "CasaOS-UserService" }, { "path": "CasaOS-LocalStorage" }, { "path": "CasaOS-AppManagement" }, { "path": "CasaOS" }, { "path": "get" } ], "settings": {} } -
打开任意
main.go文件（Ctrl-P 然后输入main.go），并在提示后安装所有与Go相关的工具。因为要下载 CasaOS 上百个依赖，这个过程会花一些时间。
¶ 构建
-
我们先尝试编译一个二进制可执行文件
这里我们以 CasaOS-LocalStorage 模块为例
cd CasaOS-LocalStorage # 进入 CasaOS-LocalStorage 仓库目录 goreleaser build --clean --snapshot -f .goreleaser.debug.yaml --id casaos-local-storage-amd64验证是否编译成功
$ dist/casaos-local-storage-amd64_linux_amd64_v1/build/sysroot/usr/bin/casaos-local-storage -v v0.3.7 -
然后我们尝试打包编译 CasaOS-LocalStorage 针对所有架构的包
goreleaser release --clean --snapshot如果成功的话，则可以在
./dist目录下看到很多.tar.gz文件，文件名中应该包含了架构信息，例如$ ls -l dist/linux-*-casaos-local-storage-*.tar.gz dist/linux-amd64-casaos-local-storage-migration-tool-v0.3.7-snapshot.tar.gz dist/linux-amd64-casaos-local-storage-v0.3.7-snapshot.tar.gz dist/linux-arm-7-casaos-local-storage-migration-tool-v0.3.7-snapshot.tar.gz dist/linux-arm-7-casaos-local-storage-v0.3.7-snapshot.tar.gz dist/linux-arm64-casaos-local-storage-migration-tool-v0.3.7-snapshot.tar.gz dist/linux-arm64-casaos-local-storage-v0.3.7-snapshot.tar.gz其中包含
migration-tool的包为对应架构下旧版本迁移至新版本的更新工具
¶ CasaOS 安装与调试
-
作为基础，我们先安装正式版的 CasaOS - 一次性
curl -fsSL get.casaos.io | sudo bash安装完成后访问 http://localhost （或者主机的 IP 地址）以验证 CasaOS 正确运行
-
停止你需要开发的模块所对应的服务 - 一次性
因为你后面需要手动运行以方便调试，而如果不停止的话正式版的模块和你正在开发的模块在启动时将会发生冲突
这里我们以 CasaOS-LocalStorage 模块为例
sudo systemctl disable --now casaos-local-storage.service -
给每个 CasaOS 模块配置
launch.json文件，添加调试方法 - (一次性)在命令中心（Ctrl-Shift-P）搜索 "
launch.json" 打开配置文件。这里我们以 CasaOS-LocalStorage 模块为例
{ "version": "0.2.0", "configurations": [ { "name": "LocalStorage (localhost)", "type": "go", "debugAdapter": "dlv-dap", "request": "launch", "port": 2345, "host": "127.0.0.1", "mode": "exec", "program": "${workspaceFolder}/dist/casaos-local-storage-amd64_linux_amd64_v1/build/sysroot/usr/bin/casaos-local-storage" } ] } -
开启调试适配器
理论上你可以像开发其他 Go 项目一样，直接点击“运行”就可以调试一个 CasaOS 模块了。
但是因为 CasaOS 在某些功能上需要 root 权限，例如对系统守护进程的管理、对存储设备的格式化等等，我们需要一个已经运行在 root 权限下的“木马”程序，以方便我们对 CasaOS 模块进行调试。否则会出现因缺少 root 权限而被拒绝执行或访问的情况。
sudo $HOME/go/bin/dlv dap --listen=:2345 --only-same-user=false -
把已经变更过代码的模块编译成二进制可执行文件（和之前的二进制文件编译命令相同）
goreleaser build --clean --snapshot -f .goreleaser.debug.yaml --id casaos-local-storage-amd64 -
开始调试
按 Ctrl-Shift-D，然后选择 LocalStorage (localhost) 并点击 F5
你可以在任意代码处设置断点，并触发相应功能，以确保调试运行成功。
¶ 测试
¶ 安装
- Ubuntu (amd64 虚拟机)
- DietPi (amd64 实体）
- Armbian (arm64 实体)
- Raspbian (树莓派 实体）
¶ 升级更新
- 设置界面中 v0.3.6 更新至最新版（非纯净更新）
- 设置界面中 上一版更新至最新版（非纯净更新）
¶ 卸载
- 全面卸载
- 保留文件卸载
¶ 商店
- 应用展示（All、分类）
- 应用详情
- 安装（所有推荐应用）
- 已安装应用显示打开（如果未启动则先启动）
- 导入外部 docker-compose.yml 进行安装
- 同时安装两个app(占用同一个端口)(pihole/ADGuard)
- 多语言支持
¶ 商店管理（纯命令行）
- 添加、删除、显示三方商店
- 确认三方商店应用被展示、可安装
¶ 生命周期
- 卸载
- 配置有效性（包括配置复原）
- 个人 Tips 添加
- 多语言支持
- 重启
- 开启
- 应用内访问 /DATA
- 关闭
- 导出 Compose YAML 并导入
- 添加外部连结
¶ 应用更新
- 存储映射升级后不丢失
- 环境变量升级后不丢失
- 其它配置升级后不丢失
- 更新过程前端有响应的提示（红色）
- 无需更新前端也要有相应的提示（绿色）
¶ 新旧应用同时展示
- 从旧版本升级上来的 CasaOS，旧应用出现在应用列表，有图标，可开始、停止、卸载
- 通过 docker run 跑一些纯容器应用，应该也出现在应用列表，有默认图标，可开始、停止、卸载
¶ U 盘
- 自动挂载（Widget 显示）
- 挂载后 Files 浏览
- 卸载
¶ 存储空间（未打开合并）
- 存储格式化
- 存储移除
- 创建存储空间
- 硬盘UI区域显示新加硬盘
- 拔 SATA 盘后，插回
¶ 合并空间
- UI 中 MergeFS 的开启
- 增加合并后 Files 中验证
- 减少合并后 Files 中验证
- 增加合并时 App 需重启
- 减少合并时提示用户数据丢失可能性
- 掉盘提醒
¶ 本地
- 上传/下载
- 创建TXT文件，输入内容保存，修改文件名
- 文件夹创建，修改命名
- 视频/照片（预览，设置成壁纸）/音乐正常播放
- 文件多选：复制，粘贴，剪切，下载，删除
¶ 局域网
- Samba 服务端 - 任意磁盘、路径可挂载
- Samba 服务端 - 可从 Windows、MacOS 写入文件、并读取
- Samba 客户端 - 可连接 Windows、MacOS、Linux 的 Samba 服务端
¶ 线上
- DropBox 绑定、文件下载、上传
- GoogleDrive 绑定、文件下载、上传
¶ 闪送
- 一对一发送文件,发送端接收端是否正常
- 一对多发送文件,发送端接收端是否正常
- 跳出闪送页面,显示该用户退出
- 退出网页是否释放内存
¶ BT、磁链接下载
- BT、磁链接下载至合并盘，并可通过内部 Files、外部 Samba 播放
- BT、磁链接下载至外挂U盘，并可通过内部 Files、外部 Samba 播放
¶ 设置UI
- 每个设置有效（包括复原）
- 系统重启与关闭
¶ Widget
- 系统状态反映客观事实
- 存储空间反映客观事实
- 网络状况反映客观事实
¶ 其他
- 问题报告
- 分享 CasaOS
- 终端访问
- 系统日志