spage/README.md

Spage - 自托管静态页面托管服务

项目处于开发阶段，暂未发布第一个版本，感兴趣的可以先订阅一下

简介

一个基于Go语言开发的, 开源自托管静态页面托管服务, 使用Caddy作为web服务器

类似于Vercel Pages, GitHub Pages, Cloudflare Pages等PaaS服务, 但它是一个开源的, 可自托管的平替

快速开始

容器化自部署

# Docker Hub源
liteyukistudio/spage:latest

# GitHub Container Registry源
ghcr.io/liteyukistudio/spage:latest

# Liteyuki Container Registry源
reg.liteyuki.org/spage/spage:latest

# 推荐优先使用公共源，即Docker Hub源和GHCR源，若访问不了再使用Liteyuki Container Registry源
# 以减轻Liteyuki Container Registry的压力

你可使用docker，podman等工具部署，也可以将其部署到Kubernetes集群中

默认容器内服务端口是8888，你可以按需暴露，并挂载/app/config.yaml到容器内部

若你需要使用最新提交，可以将latest替换为nightly标签

二进制自部署

如果不想容器化，也可以直接跑二进制，支持，可以在Release界面找到大部分平台和架构的二进制文件

支持Linux，macOS(Darwin)，Windows，FreeBSD等操作系统

AMD64兼容性：v1支持所有AMD64架构的CPU，v3支持2013年及以后的AMD64架构CPU

如果找不到你目标平台的二进制文件，可以尝试从源代码构建 go build ./cmd/server

使用Spage Cloud SaaS

无需自己部署，直接使用我们的现有实例及CDN加速服务

敬请期待...

技术栈

自托管静态页面托管服务, 基于以下技术栈构建:

• 后端: Golang, Hertz框架, Kitex(RPC框架), GORM(ORM框架)
• 前端: Next.js(React.js), TypeScript
• 数据库: SQLite3, PostgreSQL
• Web服务器: Caddy(仅提供接口)
• CLI自动化: 任意, 但尽可能和现有的前端工具链集成
• 容器化: Docker

理念:

• 尽可能的在保证完整功能的同时在开发和使用过程中不引入过多的依赖
• 考虑更具有优势和简洁完善的技术栈

基础功能

• 用户管理, 组织管理, 项目和站点管理

• 支持OAuth2以便团队使用和管理

• 可配置后台域名, 支持自定义域名 如 panel.liteyuki.org

• 支持全局域名, 可配置自定义域名, 用于站点自动生成使用 使用{version.replace(".", "_")}-{prefix}.{pages-domain} 前缀prefix随机生成, 可后期指定, 不能包含"." 版本号version默认为latest时可不加前缀

• TLS配置自定义 内网部署时, 如果外网存在一个统一网关, 可以不配置内网TLS 只需要将泛域名CNAME反向代理到内网Pages服务Http端点即可

• 动态管理站点主机路由 WEB服务器, 我们优先选用Caddy作为Web服务器, 因为它的REATful API可以用来让我们的Pages服务与Caddy交互, 动态地管理站点主机名路由 例如: 对CDN或者客户端(直连时)声明缓存时间以减少源服务器流量开销

• ClearURLs支持 支持使用 example.com/about 访问 example.com/about.html/htm 省略文件扩展名, 减少冗余

CI/CD集成

• CLI 使用TypeScript编写, 可以使用pnpm或npm等包管理器进行安装依赖, 部署, 构建等操作 部署时需要指定输出文件夹(包含index.html的目录), 站点ID以及站点Token, 还有版本号Tag(可选) CLI将输出文件夹压缩后使用指定接口上传到服务器 (可以考虑使用其他语言编写, 但是在前端构建工作流容器中使用已有前端工具链更方便)

• Git平台自动化集成 可以无缝衔接GitHub, Gitea等平台的工作流 例如: 一个项目有Release/Nightly两个稳定站点, 在CLI中推送时就需要指定站点ID, 优先返回第一个配置的自定义域名, 在PR预览模式下, 无需指定站点URL, 自动创建新站点并返回随机前缀的URL

开发者须知

在不修改默认配置的情况下，开发模式有预设配置，可以直接上手开发

Go环境配置

• 安装go工具链: Go官网
• 安装依赖go mod tidy
• 启动主控后端go run ./cmd/server

GNU Make安装

• macOS: brew install make
• Linux: 使用发行版的包管理器下载打包好的软件包
  • Debian/Ubuntu: apt install make
  • Fedora/RHEL/CentOS: dnf install make
  • Arch Linux: pacman -S make
• Windows: 前往GNU Make for Windows下载二进制自己解压到PATH中
• 或者使用WSL(Windows Subsystem for Linux)安装Linux发行版, 然后在Linux发行版中安装GNU Make
• 或者使用Chocolatey安装make包: choco install make

ProtoBuf工具链安装

protoc编译器安装

推荐方法：

• macOS: brew install protobuf
• Linux: 使用发行版的包管理器下载打包好的软件包
  • Debian/Ubuntu: apt install protobuf-compiler
  • Fedora/RHEL/CentOS: dnf install protobuf-compiler
  • Arch Linux: pacman -S protobuf

其他方法：前往ProtoBuf Release下载二进制自己解压到PATH中

protoc-gen-go 和 protoc-gen-go-grpc 安装

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# 确保 $GOPATH/bin 或 $HOME/go/bin 在 PATH 中

数据库

最早，我们提供了默认的SQLite，便于开发者开发调试 由于SQLite3是由C语言编写，CGO跨平台兼容性特别烂，便移除了对CGO的支持，开发者需要自行部署PostgreSQL进行开发 推荐使用容器化一键启动

如果你仍然想在开发中使用SQLite3，可以构建我们写好的sqlite插件，它在开发时会动态链接过去(仅支持macOS和Linux)

make plugin name=sqlite

请勿将此用于生产环境，我们不能保证它不会出事

前端环境配置

• 安装pnpm和node(或其他运行时，例如bun，deno)
• 在项目根目录下切换到前端源码目录：cd web-src
• 使用pnpm install安装依赖
• 使用pnpm dev bun dev等方式启动前端开发服务器

注意事项

• 开发模式下，前后端的域是不一样的，默认值是前端http://localhost:3000， 后端http://localhost:8888，后端配置了默认的frontend.url，来确保跨域请求及Cookie正常工作，若自定义了端口，请确保前端配置的URL与后端配置的frontend.url一致
• 开发模式下，在测试captcha时，需要将localhost（或其他域）加入到平台的白名单中
• 暂不支持mcaptcha，后续会支持
• 善用AI，但不能滥用AI，AI只能作为辅助工具

构建须知

构建前端

使用GNU Make构建(推荐)

make web

或单步构建

# 切换到前端源码目录
cd web-src
# 安装依赖
pnpm install
# 构建前端
pnpm build
# 把前端构建产物移动到后端的static/dist目录下
cp -r ./out ../static/dist
# 退出前端源码目录
cd ..

RPC IDL code gen

若你没有修改proto文件，可以跳过这一步 如果你修改了proto文件，需要重新生成IDL代码并一起推送

make proto

构建后端

使用GNU Make构建(推荐)

make spage
# 可以查看Makefile文件获取更多跨平台参数

或单步构建(不推荐，因为没有注入一些必要ldflags)

# 切换到后端源码目录
go build -o ./bin/spage ./cmd/server