Snowykami 82bbd8d27a
Some checks failed
Deploy VitePress site to Spage / build (push) Failing after 33s
Build & Publish All-in-One / Build Frontend (push) Failing after 1m53s
Build & Publish All-in-One / Build Backend (arm, 5, linux, armv5) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm, 6, linux, armv6) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm, 7, linux, armv7) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm64, darwin, arm64) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm64, freebsd, arm64) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm64, linux, arm64) (push) Has been skipped
Build & Publish All-in-One / Build Backend (arm64, windows, arm64) (push) Has been skipped
Build & Publish All-in-One / Build Backend (sse2, 386, linux, 386-sse2) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v1, amd64, darwin, amd64-v1) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v1, amd64, freebsd, amd64-v1) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v1, amd64, linux, amd64-v1) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v1, amd64, windows, amd64-v1) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v3, amd64, darwin, amd64-v3) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v3, amd64, freebsd, amd64-v3) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v3, amd64, linux, amd64-v3) (push) Has been skipped
Build & Publish All-in-One / Build Backend (v3, amd64, windows, amd64-v3) (push) Has been skipped
Build & Publish All-in-One / Build & Publish Container Images (push) Has been skipped
Build & Publish All-in-One / Publish GitHub Release (push) Has been skipped
🔧 修复UPX压缩命令,确保构建过程中的错误不会导致构建失败
2025-06-21 03:30:06 +08:00
2025-04-29 08:10:52 +08:00

spage

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的压力

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

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

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

二进制自部署

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

支持LinuxmacOS(Darwin)WindowsFreeBSD等操作系统

AMD64兼容性v1支持所有AMD64架构的CPUv3支持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编写, 可以使用pnpmnpm等包管理器进行安装依赖, 部署, 构建等操作 部署时需要指定输出文件夹(包含index.html的目录), 站点ID以及站点Token, 还有版本号Tag(可选) CLI将输出文件夹压缩后使用指定接口上传到服务器 (可以考虑使用其他语言编写, 但是在前端构建工作流容器中使用已有前端工具链更方便)

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

开发者须知

我们强烈推荐使用Unix-like系统进行开发, 例如Linux或macOS, 因为它们的兼容性更好

使用Windows你将无法使用SQLite3作为开发数据库, 需要自行部署PostgreSQL

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

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 中

数据库

  • Postgres: 推荐开发者自行部署PostgreSQL数据库进行开发PostgreSQL是一个功能强大的关系型数据库驱动兼容性更好
  • SQLite3: 通过动态链接引入避免构建时CGO导致的问题(不建议用于生产环境,我们不能保证它不会出事)

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

make plugin name=sqlite

如果你要将SQLite用于生产环境请自行编译二进制需要启用CGO如果需要在容器中使用请确保容器中安装了GNU Libc

前端环境配置

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

注意事项

为避免跨域导致的资源请求和Cookie问题

  • 开发模式下请求是先到达前端开发服务器然后通过next rewrites转发到后端开发服务器
  • 构建产物中,请求是直接到达后端服务器

Next.js的注意事项

Next.js是一个React.js框架由Vercel开发使用了Server-Side Rendering(SSR)和Static Site Generation(SSG)等技术 但是我们项目构建方式是前后端完全分离的SPA(单页面应用程式)有许多SSR特性是无法使用的

  • 所有SSR特性
  • App Router 动态路由
  • API Routes
  • next中间件
  • 域内路由 next/link 组件
  • 服务器数据获取和渲染
  • 服务端组件
  • Draft Mode

以上为常用特性,其他不可用特性请阅读Next.js文档了解更多

尽管有些特性在开发服务器中可以使用,但是在静态构建时是不被允许的,建议在贡献前先

善用AI但不能滥用AIAI只能作为辅助工具

构建须知

构建前端

使用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

开发进度

查看开发进度多维表格 - 飞书云文档

Description
Self-hosted static pages hosting and managing
Readme MIT 8 MiB
Languages
Go 59.9%
TypeScript 36.2%
CSS 2.9%
Makefile 0.9%