clace

<img src="https://yellow-cdn.veclightyear.com/835a84d5/9fb91d3b-4b0c-43d3-b7c9-47f99742af02.png" alt="Clace-logo" width="240" /> Web应用部署平台 <a href="https://github.com/claceio/clace/releases"><img src="https://yellow-cdn.veclightyear.com/835a84d5/fa14feb9-28e3-4520-bfce-d633b8fb7b49.svg" alt="最新版本"></a> <a href="https://github.com/claceio/clace/actions"><img src="https://yellow-cdn.veclightyear.com/835a84d5/01adfa71-2830-46b1-b3b1-e423e5199341.svg" alt="构建状态"></a>

概述

Clace是一个基于Apache-2.0许可的项目，用于构建内部工具的Web应用开发和部署平台。Clace允许在单台机器上轻松安全地托管多个Web应用，支持任何语言/框架。Clace是跨平台的（Linux/Windows/OSX），并提供了用于管理Web应用的GitOps工作流程。

Clace在一个轻量级二进制文件中结合了反向代理、基于超媒体的微框架和容器编排器（使用Docker或Podman）的功能。启动Clace服务器并确保Docker或Podman正在运行后，只需一个命令就可以从GitHub源代码仓库安装新应用。Clace会在第一次API调用时延迟构建镜像并启动容器。

Clace可用于在开发机器上开发任何容器化的Web应用，然后在共享服务器上部署该应用。应用直接从git仓库部署，无需构建步骤。Clace可用于部署Streamlit应用，为团队访问控制添加OAuth身份验证。

此仓库托管Clace服务器和客户端的源代码。文档网站clace.io的源代码位于docs仓库中。应用规范（用于构建应用的模板）在appspecs仓库中定义。

特性

Clace可用于：

部署容器化应用，Clace将构建和管理容器生命周期
使用Starlark构建基于超媒体的应用（无需容器）
混合方法，后端API在容器中实现，基于超媒体的UI在Clace中实现

Clace为所有应用提供以下支持：

多个应用的原子更新（全有或全无）
应用更新的暂存模式，用于在生产环境中验证代码和配置更改是否有效。
支持创建预览应用，用于尝试代码更改。
支持GitHub集成，应用直接从GitHub代码部署。
基于OAuth和SSO的身份验证
支持应用级别的基于域名和路径的路由。

对于容器化应用，Clace支持：

管理开发和生产模式下的镜像构建
为容器传递参数
从规范构建应用，支持的框架（Flask、Streamlit和包含Containerfile的仓库）无需在仓库中更改代码

对于构建基于超媒体的应用，Clace支持：

自动错误处理支持
使用esbuild自动创建ECMAScript模块。
支持TailwindCSS和DaisyUI观察器集成。
基于certmagic的自动SSL证书创建。
后端应用代码在安全沙箱中运行，具有基于允许列表的权限。
无构建步骤，开发构件可直接用于生产环境。
支持使用SQLite进行应用数据持久化
虚拟文件系统，使用基于SQLite数据库的内容哈希文件名，支持积极的静态内容缓存。
静态构件的Brotli压缩，支持HTTP早期提示以提高性能。

路线图

Clace的功能路线图包括：

目前使用SQLite进行元数据存储。计划支持PostgreSQL。这将用于实现水平扩展。
与密钥管理器集成，以安全地访问密钥。
支持暂停空闲的应用容器

设置

安装

在OSX/Linux上安装，运行

curl -L https://clace.io/install.sh | sh
source $HOME/clhome/bin/clace.env
clace server start &

在Windows上安装，运行

pwsh -Command "iwr https://clace.io/install.ps1 -useb | iex"

如果没有pwsh，请使用powershell。启动一个新的命令窗口（以获取更新的ENV值）并运行 clace server start来启动服务。

要安装应用，运行

clace app create --approve github.com/claceio/apps/system/disk_usage /disk_usage
clace app create --approve github.com/claceio/apps/utils/bookmarks /book

磁盘使用应用可在https://localhost:25223/disk_usage访问（HTTP使用端口25222）。用户名为admin，使用安装脚本打印的密码。书签管理器可在https://localhost:25223/book访问。在`app create命令中添加--auth none`以禁用身份验证。

要安装容器化应用，确保Docker或Podman正在运行，然后运行

clace app create --spec python-streamlit --param app_file=hello --approve - /streamlit_hello
clace app create --spec python-streamlit --branch master --approve github.com/streamlit/streamlit-example /streamlit

如果源仓库有Dockerfile或Containerfile，运行

clace app create --spec container --approve <source_path> /myapp

来安装应用。

从源代码构建

要安装发布版本，请按照安装文档中的步骤操作。

从源代码安装：

确保安装了最新版本的Go，版本1.21.0或更新
检出Clace仓库，进入检出的文件夹
构建clace二进制文件并放置在所需位置，如$HOME

# 确保go在$PATH中
mkdir $HOME/clace_source && cd $HOME/clace_source
git clone -b main https://github.com/claceio/clace && cd clace
go build -o $HOME/clace ./cmd/clace/

源码安装的初始配置

要使用clace服务，你需要一个包含服务密码和工作目录的初始配置文件。以下说明假设你使用$HOME/clhome/clace.toml作为配置文件，$HOME/clhome作为工作目录位置。

创建clhome目录
创建clace.toml文件，并为admin用户帐户生成一个随机密码

export CL_HOME=$HOME/clhome && mkdir $CL_HOME
cd $CL_HOME
mkdir config
git clone -C config https://github.com/claceio/appspecs
$HOME/clace password > $CL_HOME/clace.toml

这将在屏幕上打印一个随机密码，请记下该密码，用于访问应用程序。

启动服务

要启动服务，CL_HOME环境变量必须指向工作目录位置。

export CL_HOME=$HOME/clhome
$HOME/clace server start

将这些导出添加到你的shell配置文件中。服务日志将输出到$CL_HOME/logs。

默认情况下，服务将在https://localhost:25223上启动（HTTP端口25222）。

加载应用

要创建应用，运行Clace客户端

$HOME/clace app create --approve $HOME/clace_source/clace/examples/disk_usage/ /disk_usage

这将在/disk_usage创建一个示例disk_usage应用。disk_usage应用提供了一个查看文件系统磁盘使用情况的Web界面，允许用户探索占用最多磁盘空间的子文件夹。

要访问应用，请前往https://127.0.0.1:25223/disk_usage。使用admin作为用户名，并使用之前生成的密码。允许浏览器连接到自签名证书页面。或者连接到http://127.0.0.1:25222/disk_usage以避免证书相关警告。

示例应用

要创建一个显示文件列表的自定义HTML页面应用，在~/fileapp目录中创建一个包含以下内容的app.star文件：

load("exec.in", "exec")

def handler(req):
   ret = exec.run("ls", ["-l"])
   if ret.error:
       return {"Error": ret.error, "Lines": []}
   return {"Error": "", "Lines": ret.value}

app = ace.app("File Listing",
              custom_layout=True,
              routes = [ace.html("/")],
              permissions = [ace.permission("exec.in", "run", ["ls"])]
             )

以及包含以下内容的index.go.html文件：

<!doctype html>
<html>
  <head>
    <title>文件列表</title>
  </head>
  <body>
    <h1>文件列表</h1>
    {{ .Data.Error }}
    {{ range .Data.Lines }}
       {{.}}
       <br/>
    {{end}}
  </body>
</html>

运行clace app create --auth=none --approve ~/fileapp /files。应用可在https://localhost:25223/files访问。

文档

Clace文档位于https://clace.io/docs/。对于文档错误，请在[docs](https://github.com/claceio/docs)仓库中提出GitHub问题。

获取帮助

请使用Github讨论讨论Clace相关主题。请仅使用错误跟踪器报告bug和功能请求。

贡献

欢迎提交PR修复bug。提交消息应引用bug。

对于功能增强，请先提交一个带有feature标签的票据，并在进行代码更改之前讨论该变更。

Clace使用Google的go风格指南。对于应用行为相关的修复，请参考应用单元测试用例。这些测试作为常规单元测试go test ./...的一部分运行。对于API相关的更改，Clace使用commander-cli库进行自动化CLI测试。要运行CLI测试，请从clace主目录运行CL_HOME=. tests/run_cli_tests.sh。

感谢所有的贡献！