happyDomain/README.zh-cn.md

happyDomain

中文译者：Exyone

由于软件架构限制，当前 happyDomain 仅支持简体中文，繁体中文用户请安装浏览器拓展插件以进行简繁转换。造成困扰，敬请谅解。

happyDomain 是一款免费的 Web 应用，可集中管理来自不同注册商和托管商的域名。

它由 Golang 编写的 HTTP REST API（主要基于 https://stackexchange.github.io/dnscontrol/ 和 https://github.com/miekg/dns）与 Svelte 构建的精美 Web 界面组成。 作为单一无状态的 Linux 二进制文件运行，支持多种数据库（当前支持 LevelDB，更多选项即将推出）。

主要特性：

• 高性能 Web 界面，响应迅速
• 支持多域名管理
• 支持 60+ DNS 提供商（含动态 DNS、RFC 2136），得益于 DNSControl
• 支持最新资源记录类型，得益于 CoreDNS 库
• 区域编辑器支持差异对比，部署前轻松审查变更
• 保留部署变更历史记录
• 上下文帮助
• 支持多用户认证或单用户无认证模式
• 兼容外部认证（OpenId Connect 或 JWT 令牌：Auth0 等）

happyDomain 已可投入使用，但仍需不断完善：这是一个精心打造的概念验证版本，您的反馈将助力其不断进化！

鉴于 DNS 配置和用户需求的多样性，我们尚未发现所有潜在问题。若遇问题，请勿离去：向我们反馈问题所在。 我们响应迅速，每个报告的 bug 都能帮助改进工具，惠及众人。

无论使用体验如何，我们都期待您的反馈！ 您如何看待我们简化域名管理的方式？您的初步印象有助于我们根据您的实际期望来指引项目方向。

使用 Docker

我们是由 Docker 赞助的开源项目！因此您可以轻松使用 Docker/podman/kubernetes/... 来试用或部署应用。

使用 docker compose 启动 happyDomain：

git clone https://framagit.org/happyDomain/happyDomain.git
cd happyDomain
docker compose up

或直接使用 docker run：

docker run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain

此命令将在数秒内启动 happyDomain，用于评估测试（无认证、临时存储等）。使用浏览器访问 http://localhost:8081 即可体验！

部署 happyDomain，请查阅 Docker 镜像文档。

从二进制文件安装

预编译二进制文件下载地址：https://get.happydomain.org/

选择目录（最新版本或 master 分支），然后选择与您的操作系统和 CPU 架构对应的二进制文件。

使用 happyDomain

二进制文件附带默认配置，可直接启动。在终端中运行以下命令即可：

./happyDomain

初始化完成后，应显示以下信息：

Admin listening on ./happydomain.sock
Ready, listening on :8081

访问 http://localhost:8081/ 开始使用 happyDomain。

数据库配置

默认使用 LevelDB 存储引擎。可使用 -storage-engine 选项更改存储引擎。

运行 ./happyDomain -help 查看可用存储引擎：

    -storage-engine value
    	在 [inmemory leveldb oracle-nosql postgresql] 中选择存储引擎 (默认 leveldb)

LevelDB

LevelDB 是轻量级嵌入式键值存储（类似 SQLite，无需额外守护进程）。

    -leveldb-path string
    	LevelDB 数据库路径 (默认 "happydomain.db")

默认在二进制文件所在目录创建 happydomain.db 目录。可更改为更有意义或更持久的路径。

inmemory

数据存储于内存中，服务停止后数据即丢失。

PostgreSQL

PostgreSQL 支持主要面向已部署 PostgreSQL 数据库基础设施的环境。这允许您利用现有数据库设置、备份流程和运维工具，无需部署额外数据库系统。

happyDomain 以键值存储模式使用 PostgreSQL，将所有数据存储在包含 key 和 value 列的单张表中。虽然可行，但请注意，与专用键值存储相比，PostgreSQL 并非键值工作负载的最佳选择。若从头部署且需超出 LevelDB 的可扩展性，请考虑使用专为键值操作设计的存储后端。

    -postgres-database string
      	PostgreSQL 数据库名称 (默认 "happydomain")
    -postgres-host string
      	PostgreSQL 服务器主机名 (默认 "localhost")
    -postgres-password string
      	PostgreSQL 密码
    -postgres-port int
      	PostgreSQL 服务器端口 (默认 5432)
    -postgres-ssl-mode string
      	PostgreSQL SSL 模式 (disable, require, verify-ca, verify-full) (默认 "disable")
    -postgres-table string
      	键值存储的 PostgreSQL 表名 (默认 "happydomain_kv")
    -postgres-user string
    	PostgreSQL 用户名 (默认 "happydomain")

Oracle NoSQL Database

Oracle NoSQL Database 是来自 Oracle Cloud Infrastructure (OCI) 的全托管云服务，提供按需吞吐量和高可用的存储配置。happyDomain 可将其作为可扩展的云端存储后端用于生产部署。

使用 Oracle NoSQL Database 需拥有 OCI 账户并创建 NoSQL 表。表需包含主键字段 key（字符串类型）和 value 字段（JSON 类型）存储数据。认证使用 OCI 的 IAM 和 API 签名密钥。

配置以下选项连接 happyDomain 至 Oracle NoSQL Database：

    -oci-compartment string
      	NoSQL 数据库所在的 OCI 隔间 ID
    -oci-fingerprint string
      	OCI 用户 API 密钥指纹
    -oci-private-key-file string
      	给定用户的 OCI 私钥文件路径
    -oci-region string
      	NoSQL 数据库所在的 OCI 区域 (默认 "us-phoenix-1")
    -oci-table string
      	存储值的表名 (默认 "happydomain")
    -oci-tenancy string
      	NoSQL 数据库所在的 OCI 租户 ID
    -oci-user string
      	访问 NoSQL 数据库的 OCI 用户 ID

数据库管理系统

MySQL/Mariadb 等 DBMS 已不再支持，亦无相关计划。

持久化配置

二进制文件会自动查找以下配置文件：

• 当前目录下的 ./happydomain.conf；
• $XDG_CONFIG_HOME/happydomain/happydomain.conf；
• /etc/happydomain.conf。

仅使用找到的第一个文件。

也可通过命令行参数指定自定义路径：

./happyDomain /etc/happydomain/config

配置文件格式

注释行必须以 # 开头，不支持行尾注释。

每行放置配置选项名称和期望值，用 = 分隔。例如：

storage-engine=leveldb
leveldb-path=/var/lib/happydomain/db/

环境变量

还会查找以 HAPPYDOMAIN_ 开头的特殊环境变量。

使用以下环境变量可达到与上述示例相同的效果：

HAPPYDOMAIN_STORAGE_ENGINE=leveldb
HAPPYDOMAIN_LEVELDB_PATH=/var/lib/happydomain/db/

只需将短横线替换为下划线即可。

需要 OVH API？

OVH 没有简单的 API 密钥或凭据，需通过 Web 流程获取密钥。

启动认证流程，happyDomain 实例需配备专用应用程序密钥。

连接 OVH，请按以下说明操作。

构建

依赖项

构建 happyDomain 项目需具备以下依赖项：

• go；
• nodejs，已测试版本 22；
• swag，已测试版本 1.16（可通过 go install github.com/swaggo/swag/cmd/swag@latest 安装）。

构建步骤

1. 首先准备前端，安装 node 模块依赖：

pushd web; npm install; popd

2. 然后生成 Go 代码使用的资源文件：

go generate -tags swagger,web ./...

3. 最后编译 Go 代码：

go build -tags swagger,web ./cmd/happyDomain

此命令将创建独立二进制文件 happyDomain。

开发环境

若要为前端做贡献，而非每次修改后都重新生成前端资源（使用 go generate），可使用开发工具：

一个终端中使用以下参数运行 happydomain：

./happyDomain -dev http://127.0.0.1:5173

另一终端运行 node 部分：

cd web; npm run dev

此设置不使用集成到 go 二进制文件中的静态资源，而是将所有静态资源请求转发至 node 服务器，实现动态重载等功能。