HASH

创建账户

[创建账户] 以开始使用。

登录

[登录] 以访问您的账户。

跳过排队

当您首次创建账户时，可能会被加入等待列表。若要跳过排队，请在登录后按照 HASH 仪表板中显示的说明操作。所有提交均由团队成员审核。

在本地运行 HASH

以下说明用于在代码库上工作 — 应用服务以原生方式运行，支持热重载，并针对容器化基础设施。若要改为从容器镜像运行整个技术栈（主机上无需工具链），请遵循设置指南。

先决条件

请先在主机上安装以下内容：

• Git (≥ 2.17)
• Docker (≥ 20.10)，包括：
  • Docker Compose (≥ 2.17) — 编排技术栈
  • Docker Buildx (≥ 0.10) — 构建镜像
• mise (≥ 2026.6.13) — 安装并固定 Node、Rust、protoc 及其他所需工具版本

为 Docker 分配至少 8 GB RAM（偏好设置 → 资源），并为构建产物、镜像和数据卷保留约 15 GB 的磁盘空间。

检查您的版本：

git --version            # ≥ 2.17
docker --version         # ≥ 20.10
docker compose version   # ≥ 2.17
docker buildx version    # ≥ 0.10
mise --version           # ≥ 2026.6.13

设置

1. 克隆仓库并进入该目录：

   git clone https://github.com/hashintel/hash.git && cd hash

2. 安装固定版本的工具链（mise trust 每次克隆需要执行一次），然后在您的 shell 中 激活 mise：

   mise trust && mise install

3. 安装 JavaScript 依赖项：

   yarn install

4. 在仓库根目录创建一个 .env.local。仅 AI 功能需要真实密钥——其他情况下使用占位值即可：

   OPENAI_API_KEY=dummy
   ANTHROPIC_API_KEY=dummy
   HASH_TEMPORAL_WORKER_AI_AWS_ACCESS_KEY_ID=dummy
   HASH_TEMPORAL_WORKER_AI_AWS_SECRET_ACCESS_KEY=dummy

.env.local 被 git 忽略，并覆盖 .env 和 .env.development。除非您打算更改默认值，否则请勿编辑其他 .env 文件。

5. 启动容器化基础设施：

   yarn compose up -d

这将运行 dev 和 observability 配置文件 — Postgres、Redis、Kratos、Hydra、Temporal、Vault 和 MinIO，以及 Grafana 堆栈（http://localhost:3001) 和 Temporal UI（http://localhost:3100/namespaces/HASH)。图层未包含在内；您需要在下方作为应用的一部分运行它。

6. 启动 HASH。最简单的方法是原生运行所有内容（这会从 Rust 编译图，在冷启动首次构建时耗时 10–20 分钟）：

   yarn start

对于 api 和 frontend 的热重载，请改为在单独的终端中分别运行 graph 和 app：

yarn start:graph   # terminal 1 — compiles and runs the graph
yarn dev           # terminal 2 — api + frontend with hot-reload

开发模式 API 会初始化三个用户（密码 password）：alice@example.com、bob@example.com（普通用户）和 admin@example.com（管理员）。当 API 日志输出 localhost:5001 后，访问 http://localhost:3000。

跳过 Rust 构建

如果你没有在开发图本身，请改用 Docker 运行，而不是在本地编译 Rust —— 添加 hgres 配置文件，并仅以原生方式启动 api + frontend：

yarn compose --profile hgres up -d   # infrastructure + graph in Docker
yarn dev                             # api + frontend only

运行浏览器插件

如果你需要在本地运行浏览器插件，请参阅 apps/plugin-browser 目录中的 the README.md]。

重置本地数据库

如果你需要重置本地数据库，以清除测试数据或因为其在开发过程中已损坏：

1. 运行 yarn compose down -v（这将停止 Docker 服务并删除卷）
2. 运行 yarn compose up -d 以重新启动所有服务

发送邮件

HASH 中的邮件发送由 Kratos（针对身份验证相关的邮件）或通过 HASH API Email Transport（针对其他所有邮件）处理。

要使用 AwsSesEmailTransporter，请在运行应用程序之前在终端中设置 export HASH_EMAIL_TRANSPORTER=aws，以及 SYSTEM_EMAIL_ADDRESS 和 SYSTEM_EMAIL_SENDER_NAME（它们控制邮件显示的地址和名称）。此邮件传输器需要有效的 AWS 凭据才能工作。

事务性邮件模板位于以下位置：

• Kratos 邮件位于 ./infra/compose/kratos/templates/]。此目录包含以下模板：
  • recovery_code] - 使用代码进行 UI 账户恢复流程的邮件模板。
    • 当邮件属于已注册的 HASH 用户时，它将使用 valid 模板，否则使用 invalid 模板。
  • verification_code] - 使用代码进行 UI 账户注册流程的邮件验证模板。
    • 当邮件属于已注册的 HASH 用户时，它将使用 valid 模板，否则使用 invalid 模板。
• HASH 邮件位于 apps/hash-api/src/email/index.ts]

将 HASH 部署到云端

请参阅 自托管指南 以了解如何在您自行运营的基础设施上运行 HASH。完整的 Docker Compose 拓扑结构 —— 包括 graph、API、frontend、auth、workflows、storage 和 observability —— 位于 infra/compose/，是自托管部署的起点。

仓库结构

此仓库的内容分为几个主要部分：

• /apps 包含驱动我们可运行 applications 的主要代码
  • HASH 应用程序本身被划分为各种不同的服务，可以在该目录中找到。
• /blocks 包含我们的公开 Block Protocol blocks
• /infra 包含部署脚本、实用工具以及其他在运行我们的应用时有用的 infrastructure
• /libs 包含 libraries，包括 npm 包和 Rust crate
• /tests 包含跨越一个或多个应用、blocks 或 libs 的端到端测试和集成测试

环境变量

以下是可能的环境变量列表。所有必需项均已具有默认值。

运行应用程序时，您无需设置任何环境变量。

通用 API 服务器环境变量

• NODE_ENV: （"development" 或 "production"）运行时环境。控制 默认日志级别和输出格式。
• PORT: API 将监听的端口号。

AWS 配置

如果您想使用 AWS 进行文件上传或发送邮件，需要进行配置：

• AWS_REGION: 区域，例如 us-east-1
• AWS_ACCESS_KEY_ID: 您的 AWS 访问密钥
• AWS_SECRET_ACCESS_KEY: 您的 AWS 秘密密钥
• AWS_S3_UPLOADS_BUCKET: 用于文件上传的存储桶名称（如果您想使用 S3 进行文件上传），例如：my_uploads_bucket
• AWS_S3_UPLOADS_ACCESS_KEY_ID: （可选）用于文件上传的 AWS 访问密钥 ID。如果 API 未通过其他方式（例如通过 IAM 角色）获得访问存储桶的授权，则必须与秘密访问密钥一起提供。
• AWS_S3_UPLOADS_SECRET_ACCESS_KEY: （可选）用于文件上传的 AWS 秘密访问密钥。
• AWS_S3_UPLOADS_ENDPOINT: （可选）用于 S3 操作的端点。如果未设置，则使用给定区域的 AWS S3 默认值。如果您使用的是其他 S3 兼容的存储提供商，则此设置很有用。
• AWS_S3_UPLOADS_FORCE_PATH_STYLE: （可选）如果您的 S3 配置需要路径样式而非虚拟主机样式的 S3 请求，请设置 true。

对于某些浏览器内功能（例如文档预览），您必须将存储桶上的 Access-Control-Allow-Origin 请求头配置为 '*' 以外的值。

文件上传

默认情况下，文件在本地上传，这不推荐用于生产环境。也可以在 AWS S3 上上传文件。

• FILE_UPLOAD_PROVIDER：用于文件上传的提供者类型。可能的值为 LOCAL_FILE_SYSTEM 或 AWS_S3。如果选择 S3，则需要配置上述 AWS_S3_UPLOADS_ 变量。
• LOCAL_FILE_UPLOAD_PATH：如果使用本地文件系统存储提供者，则用于存储上传文件的相对路径。默认为 var/uploads（var 文件夹是通常用于应用程序数据的文件夹）

电子邮件

在开发过程中，虚拟邮件传输器会将邮件写入本地文件夹。

• HASH_EMAIL_TRANSPORTER：dummy、aws 或 smtp。如果设置为 dummy，则在开发或测试环境中将使用本地虚拟邮件传输器（它会记录到控制台）。
• DUMMY_EMAIL_TRANSPORTER_FILE_PATH：默认为 var/api/dummy-email-transporter/email-dumps.yml
• SYSTEM_EMAIL_SENDER_NAME：邮件发件人的显示名称（如果传输方式为 aws 或 smtp 则必填）
• SYSTEM_EMAIL_ADDRESS：邮件发件人的电子邮件地址（如果传输方式为 aws 或 smtp 则必填）
• SMTP_SERVER_HOST：SMTP 服务器的主机（如果传输器为 smtp 则必填）
• SMTP_SERVER_PORT：SMTP 服务器的端口（如果传输器为 smtp 则必填）
• SMTP_SERVER_USERNAME：SMTP 服务器的身份验证用户名（如果 API 已自动身份验证，则为可选）
• SMTP_SERVER_PASSWORD：SMTP 服务器的密码（如果 API 已自动身份验证，则为可选）

Postgres

• POSTGRES_PORT（默认：5432）

各种服务也有各自的配置。

Postgres 超级用户通过以下方式配置：

• POSTGRES_USER（默认值：postgres）
• POSTGRES_PASSWORD（默认值：postgres）

Kratos 的 Postgres 信息通过以下方式配置：

• HASH_KRATOS_PG_USER（默认值：kratos）
• HASH_KRATOS_PG_PASSWORD（默认值：kratos）
• HASH_KRATOS_PG_DATABASE（默认值：kratos）

Temporal 的 Postgres 信息通过以下方式配置：

• HASH_TEMPORAL_PG_USER（默认值：temporal）
• HASH_TEMPORAL_PG_PASSWORD（默认值：temporal）
• HASH_TEMPORAL_PG_DATABASE（默认值：temporal）
• HASH_TEMPORAL_VISIBILITY_PG_DATABASE（默认值：temporal_visibility）

图查询层的 Postgres 信息通过以下方式配置：

• HASH_GRAPH_PG_USER（默认值：graph）
• HASH_GRAPH_PG_PASSWORD（默认值：graph）
• HASH_GRAPH_PG_DATABASE（默认值：graph）

Redis

• HASH_REDIS_HOST（默认值：localhost）
• HASH_REDIS_PORT（默认值：6379）

Rudderstack 遥测

• HASH_API_RUDDERSTACK_KEY：用于产品分析的 Rudderstack 写入密钥。留空以禁用遥测。事件上的 environment 标签由 ENVIRONMENT 派生。（可选）

其他

• FRONTEND_URL：用于链接的前端网站 URL（默认值：http://localhost:3000）
• NOTIFICATION_POLL_INTERVAL：前端轮询新通知的间隔（以毫秒为单位），或 0 表示不轮询。（默认值：10_000）
• HASH_INTEGRATION_QUEUE_NAME 实体更新发布到的 Redis 队列的名称
• API_ORIGIN：可以访问 API 服务的源（默认值：http://localhost:5001）
• SESSION_SECRET：用于签署会话的密钥（默认值：secret）
• LOG_LEVEL：应省略的运行时日志级别，设置为 debug、info、warn、error（默认值：info）
• BLOCK_PROTOCOL_API_KEY：用于从 Þ Hub 获取块的 API 密钥。在 https://blockprotocol.org/settings/api-keys 生成密钥。