---
title: "安装 Appaloft"
description: "通过二进制包或 Docker 镜像安装 Appaloft。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.appaloft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 Appaloft

## 目标

在自己的服务器上安装并运行一份完整的 Appaloft 实例(包含 Web 控制台和公共文档)。

## 适用场景

- 需要完全掌控数据归属,不希望使用托管的 Appaloft Cloud。
- 在内网或无公网访问的环境中部署 Appaloft。

## 前置条件

- 一台可以运行 Docker 的 Linux 服务器(推荐),或者已下载对应平台的二进制包。
- 如果要绑定域名,需要提前把 DNS 指向这台服务器,并开放 `80`/`443` 端口。

## 输入与默认值

`appaloft serve` 的根路径提供 Web 控制台,`/docs/*` 提供公共文档——二进制包同时内嵌这两部分的静态资源,单机离线环境也能打开帮助文档。

## CLI 操作步骤

### 最简安装(推荐)

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh
```

`install.sh` 会把 Appaloft 安装成一套 Docker Compose Stack,默认使用 PostgreSQL,适合生产自托管。

### 使用嵌入式数据库(单机场景)

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --database pglite
```

单机便携控制台可以继续使用嵌入式 PGlite;这种模式下 Appaloft 状态保存在挂载到 `/appaloft-data` 的持久 Docker Volume 中。

### 绑定域名

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --domain console.example.com
```

没有配置域名时,控制台可以通过服务器的 `3721` 端口访问。这个域名是 **Appaloft 实例自己的控制台入口**,不是项目资源的自定义域名,也不会创建部署快照或域名绑定。只有在外部反向代理已经负责公开入口时,才使用 `--proxy none`。

### 离线 / 内网安装

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --image <registry>/appaloft:<tag> --skip-image-pull
```

`--image` 用于指定预加载的 Appaloft 镜像;只有镜像已经存在于本机 Docker daemon 时,才加 `--skip-image-pull`。

### Docker Swarm <a id="docker-swarm-runtime-target" />

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --database pglite --orchestrator swarm --stack-name appaloft
```

只有明确希望安装器初始化单节点 Swarm manager 时,才加 `--swarm-init`。

## 预期输出与状态

安装脚本会在 Appaloft HTTP 服务启动前自动应用待执行的数据库迁移。安装完成后会打印控制台 URL;默认还会启动一个 Appaloft 自己管理的 Traefik 边缘代理。

安装器会为产品登录会话生成并复用一个稳定密钥,保存在安装目录的 `.env` 中——**升级或修复时不要删除这个值**,否则已有登录会话会全部失效。

## 验证

打开安装器打印的控制台 URL,确认页面正常加载;然后按照[创建首个管理员账号](/docs/self-hosting/first-admin/)完成初始账号创建和登录。

## 回滚 / 恢复

迁移失败时容器不会通过健康检查,安装器会报错并提示查看容器日志;修复数据库或镜像问题后,重新运行同一条安装命令即可(安装器是幂等的,会复用已有配置和数据卷)。

不要把数据库密码、GitHub Token、SSH Key 或部署身份值写进仓库配置——这些值应该放在主机环境变量、CI 密钥库,或安装后的 Appaloft 实例内部。

## 进阶:链路追踪

```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --trace jaeger
```

安装器会启动一个 Jaeger all-in-one 容器,把 Appaloft 的 OTLP 端点指向内部 collector,并把追踪链接写回 Jaeger UI(默认绑定 `127.0.0.1:16686`)。如果 Jaeger 通过其他域名公开,需要把 `APPALOFT_TRACE_LINK_BASE_URL` 设为这个外部 URL,详见[运行时配置参考](/docs/reference/configuration/)。

## 进阶:临时公网访问 <a id="advanced-tunnels" />

已安装的 Appaloft 可以为本机或私网 HTTP 源启动有时限的临时公网隧道(Cloudflare Quick Tunnel 或 ngrok),用于快速给外部访问者一个临时地址:

```bash
appaloft tunnel start --provider cloudflare-quick --origin http://127.0.0.1:3000 --duration-minutes 60
appaloft tunnel list
appaloft tunnel show <tunnelId>
appaloft tunnel revoke <tunnelId>
```

Provider 凭据只从对应 Provider 的环境变量读取(例如 ngrok 使用 `NGROK_AUTHTOKEN`),不会被持久化或在查询结果中回显。公共源地址、带凭据的 URL、非 HTTP scheme 会被直接拒绝。

## 故障排查链接

- [常见故障与恢复](/docs/troubleshoot/recovery/)
- [运行时配置参考](/docs/reference/configuration/)

## 相关参考页面

- [创建首个管理员账号](/docs/self-hosting/first-admin/)
- [内嵌文档资产](/docs/self-hosting/embedded-docs/)
- [升级 Appaloft](/docs/self-hosting/upgrades/)

Source: https://docs.appaloft.com/self-hosting/install/index.mdx