Glazecalc

Glazecalc

为陶艺师提供免费的釉料化学计算。 输入釉料配方，即可查看其单位分子式 （UMF）：釉料在窑中形成的助熔剂、氧化铝和二氧化硅，以及它们的比例。将配方、 原料、着色剂、烧制日志和笔记保存在同一个私人笔记本中。

glazecalcapp.com：无需账号即可试用。

功能介绍

• 输入配方，即时生成分子式。 使用你自己的原料或标准原料配制釉料，查看其氧化物分子式，按助熔剂、稳定剂和成玻璃体分组，并显示二氧化硅与氧化铝的比例。釉料化学家正是这样比较配方、排查问题和替换原料的。可将配方缩放为百分比、最小整数份数，或以克、磅为单位的批次（磅数同时显示磅和盎司）；着色剂可按基料百分比、份数或克数计量。保存配方后继续编辑，或打开已保存的配方进行修改。

• **并排比较两种配方，**逐项比较氧化物和计算出的热膨胀率，还可用现代替代原料试做旧配方（例如，用 G-200 EU 替代已停产的 Custer Spar），并与原配方对比。若替换原料无法一对一替代，系统会重新计算用量，尽可能少地调整原配方；原料可从你所在地区销售的材料中选择，也可使用你添加的材料。系统还会说明每种原料的作用，以及超过建议限值后需要注意的事项。

• **按现有原料匹配：**仅用手头现有原料重新配制配方；原料清单保存在你的账户中。

• 分析与限值：将分子式与 Hesselberth & Roy 的稳定釉料限值或 Glazecalc 自带的限值进行对照，并采用配方中保存的烧成设置；还可查看二氧化硅与氧化铝的Stull 图，其中标出哑光、半哑光和亮光区域。

• **比重与水量：**称量一定体积的釉料以测出比重（SG），再计算将桶中釉料调至目标比重所需的水量，或配制新批次所需的水量。

• 粘贴配方，来源可以是网站、电子表格或笔记：保存之前，先查看每一行是如何读取的，以及对应识别为哪种原料。

• **试片混合：**将两种、三种或四种配方混合，制成编号试片，并列出每片的称量用量和化学组成。

• 根据你支付的价格计算每批成本；价格以一种货币保存在你的账户中，仅你可见。还可打印配料单供釉料间使用，其中包含批次编号、目标比重和原料危害信息（除非你选择显示，否则不打印价格）。

• 分享配方：生成只读链接，任何人都可以无需账户打开，查看分子式及其计算过程；你可以随时停止分享。

• **使用 Google、GitHub 或 Microsoft 登录，**也可使用密码、两步验证或通行密钥登录。

• **通过 AI 助手使用：**Claude、ChatGPT、GitHub Copilot、Cursor、Gemini 等可通过 /mcp 上的 Model Context Protocol（MCP）服务使用计算功能；连接后还可访问你自己的记录：应用会登录 Glazecalc 自有的 OAuth 服务，由你决定是否授权（默认只读，除非你也允许修改），或者你可以为它们创建访问令牌。已连接的应用页面会显示每个应用执行的操作、恢复它移至回收站的内容并撤销其访问权限；“助手”页面会说明如何连接。

• **为陶艺初学者提供的指南，**均注明来源：从基础原理入门的施釉指南，附术语表；釉料制作方法；安全混料与通风；有儿童和宠物的家庭陶艺；以及使用测温锥、窑炉自动断电器和手动开关烧制基础窑炉。另有英文版指南配套 John Britt 的免费在线釉料课程，按单元链接课程视频并附练习。

• **默认不使用铅，除非你选择使用；**还可重配旧的含铅釉料以去除铅：Replace lead 会保留釉料中的二氧化硅和氧化铝，并用硼和其他助熔剂替代铅的作用；可选用你所在地区销售的无铅基础熔块，再搭配最多四种其他原料，或在无铅基料上保留原有颜色。

• **打印供釉料间使用：**打印包含分子式和分析结果的完整配方，或只打印批次清单，以便称量时逐项勾选；若所有原料称入同一桶，还会显示累计总量。可排在一张 Letter 或 A4 纸上；重量单位为克，或按账户设置显示为磅和盎司。

• **你的地区与计量设置：**根据你所在地区的习惯格式输入数字和日期（12,5 或 12.5 均可），选择 °C 或 °F、Orton 测温锥、SK 测温锥（JIS R 8101）或按温度烧成；系统还会提供当地销售的标准原料。指南覆盖 37 个国家，包含紧急联系电话、釉料原料商店、当地销售且最接近配方所列原料的材料、工作场所二氧化硅粉尘限值，以及釉面陶器的食品接触限值（其中 36 个国家有相关限值；新西兰未查到官方限值）。每项信息都经过核实，来源为官方网站或商家自有页面。

• **支持 39 种语言：**欧盟每个国家的官方语言（保加利亚语、克罗地亚语、捷克语、丹麦语、荷兰语、英语、爱沙尼亚语、芬兰语、法语、德语、希腊语、匈牙利语、爱尔兰语、意大利语、拉脱维亚语、立陶宛语、马耳他语、波兰语、葡萄牙语、罗马尼亚语、斯洛伐克语、斯洛文尼亚语、西班牙语和瑞典语），以及日语、土耳其语、繁体中文、韩语、简体中文、泰语、越南语、印度尼西亚语、阿拉伯语和乌尔都语（从右向左书写）、印地语、孟加拉语、泰米尔语、马拉地语和卡纳达语；每种语言均有独立地址（/de/recipe）。 根据供应商目录，使用各语言的术语表进行 AI 翻译，并经审核；安全文本还会通过回译检查。每个翻译页面都会说明这一点，并链接到一个表单，供用户提出更合适的译法。

  每段文本都是一条消息（使用带 ICU 复数规则的 Transloco），指南则按语言编写为 Markdown（翻译制作方式）。

• **自定义配色：**浅色、深色或跟随设备设置，并提供六种以釉料命名的配色方案， 每种方案在两种模式下都清晰易读。

• **包含 167 种材料及 37 种着色剂和添加剂的标准库，**数据来自制造商的 数据表，适用于美国、英国、欧盟、澳大利亚和新西兰。每种材料均注明来源和其他名称，并在数据表中列出的情况下标明危害。已停产的材料 仍保留供旧配方使用，并指向其现代替代品。可将着色剂计入统一配方，或将其排除， 以便与其他计算器进行比较。

• **自定义材料，**可根据化学式或供应商的分析数据添加；也可在基础釉料中加入着色剂和 乳浊剂。

• **工作室笔记本：**烧制记录（时间、温度、锥号）、笔记，以及有关混料、施釉和烧制的通俗 建议。

• **立即试用：**整个应用都可作为试用版使用，并会生成诸如“斑点静谧窑炉”这样的名称。创建账户即可保留所有内容；试用数据会在 14 天后删除。

• 支持从手机到桌面的浅色和深色模式。免费且开源。

亮点

如果你正在阅读代码：

• 将一个 2017 年的 AngularJS 应用重建为 Angular 22（独立组件、signals、无 zone.js、 严格模板），并使用 Express 5、Mongoose 9 和 Node 24 构建 TypeScript 服务，可直接运行 .ts 文件，无需构建步骤（ADR 8）， 并重新上线。 案例研究介绍了具体过程。
• **在三个层面进行测试，并在每个拉取请求和推送到 master 时于 CI 中运行：**约 1,000 项服务端测试（语句覆盖率 98%）直接针对应用进程运行；700 多项 Angular 单元测试（92%）；约 175 项 Playwright 浏览器测试， 包括使用 axe 对浅色和深色模式下的每个页面进行无障碍检查、在伪区域设置中检查每个页面以找出未标记为可翻译的文本，以及 在手机屏幕宽度下检查每种语言的每个页面。
• 浏览器和测试共用一个釉料化学库，并通过手工计算得出的数值进行校验 （ADR 4）。
• **通过审批进行无密钥部署：**GitHub Actions 通过 OIDC 获取短期 AWS 凭证，用于一个只能在此应用的实例上运行单个 SSM 命令文档的角色。没有 SSH，也不存储 AWS 密钥；健康检查失败时会回滚 （ADR 2）。
• **生产环境每月费用约为 $13：**一台 Graviton EC2 实例，搭配 Docker Compose、nginx 和 Let's Encrypt；内容安全策略带有子资源完整性检查；每晚备份到 S3；并配置快照和告警 （ADR 1、 ADR 3）。
• **谨慎处理账户：**使用 bcrypt；采用带版本号的 HS256 令牌，因此修改密码会让所有设备退出登录；令牌保存在 httpOnly、SameSite=Strict Cookie 中，并进行跨站请求检查； 通过 Amazon SES 发送经过哈希处理的一次性重置链接，并配置 DKIM、SPF 和 DMARC； 设置速率限制；每次查询都进行所有权检查；更改邮箱或 删除账户时需要提供当前密码（ADR 5、 ADR 6）。
• **试用账户也是真实账户：**自动生成名称，在保留的 .invalid 域名下使用占位邮箱，确保每个邮箱地址都唯一；可原地转换为账户（或在登录时转换到现有账户）；设有防滥用限制， 并每小时清理一次（ADR 7）。
• **生产构建上的 Lighthouse（桌面端）：**性能 99；无障碍、最佳实践和 SEO 均为 100；没有布局偏移。

组件如何协作

flowchart LR
  browser([Browser]) -->|HTTPS| nginx
  subgraph ec2 [EC2 t4g.micro, Debian 13]
    nginx["nginx<br/>Let's Encrypt, headers, gzip"] --> app["Node 24, Express 5<br/>/api and the Angular client"]
    app --> mongo[("MongoDB 9")]
  end
  app -->|SMTP| ses[Amazon SES]
  mongo -.->|nightly dump| s3[(S3 backups)]
  subgraph github [GitHub]
    ci["CI: lint, format, 3 test suites,<br/>image check"] --> ghcr[("GHCR image<br/>arm64 and amd64")]
    deploy["Deploy workflow<br/>approval, OIDC"]
  end
  deploy -->|"SSM: glazecalc-deploy"| ec2
  ghcr -.->|pull| app

浏览器只与一个来源通信：nginx 终止 HTTPS，并将所有请求转发给单个 Node 进程；该进程在 /api 下提供 JSON API，并为其他所有路径提供构建后的 Angular 客户端。 部署时会通过 SSM 在实例上运行 deploy.sh：拉取新镜像、启动镜像；若健康检查失败，则恢复到上一个版本。

部分	构建技术
客户端	Angular 22、TypeScript（严格模式）、带 ICU 消息的 Transloco、带自定义调色板的 Bootstrap 5、Vitest
服务端	由 Node.js 24 直接运行的 TypeScript、Express 5、Mongoose 9、JWT、bcrypt、Mocha
数据	MongoDB 9
基础设施	AWS（EC2、SSM、SES、S3、CloudWatch、带 OIDC 的 IAM）、Docker Compose、nginx、certbot
交付	GitHub Actions、GHCR、带 axe 的 Playwright、ESLint、Prettier、Dependabot

在本地运行

你需要 Node.js 24（24.15 或更高版本）和 npm 11，以及 MongoDB Community Server 9.0（也可使用 4.4 或更高版本）。

git clone https://github.com/AaronFilson/glazecalc.git
cd glazecalc
npm install
npm run db                        # 在第二个终端中于 ./db 启动 MongoDB；保持运行
npm run seed                      # 标准材料、添加剂和建议
npm run dev                       # 然后打开 http://localhost:3000

APP_SECRET 和 MONGODB_URI 等设置可写入 .env 文件（复制 .env.example，其中说明了各项设置）；脚本使用 Node 内置的 --env-file 支持加载该文件。在生产环境之外，电子邮件（例如密码重置链接）会打印到控制台。

所有工具、安装链接和版本检查

工具	用途	安装	检查版本
Git	克隆代码库	下载	git --version
Node.js 24 LTS（24.15 或更高版本）	构建和运行应用	下载 Node.js	node --version
npm 11（随 Node.js 24 提供）	安装软件包、运行脚本	安装 npm	npm --version
MongoDB Community Server 9.0（也可使用 4.4 或更高版本）	数据库	下载 MongoDB	mongod --version
现代浏览器，例如 Firefox 或 Chrome	使用应用	下载 Firefox	浏览器中的“帮助”→“关于”

根据用途，以下工具为可选：

| 工具 | 所需用途 | 安装 | 检查版本 | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [nvm-windows](https://github.com/coreybutler/nvm-windows) 或 [nvm](https://github.com/nvm-sh/nvm)（macOS、Linux） | 在不同 Node.js 版本之间切换 | [nvm-windows releases](https://github.com/coreybutler/nvm-windows/releases)、[nvm install script](https://github.com/nvm-sh/nvm#installing-and-updating) | `nvm version`（Windows）、`nvm --version` | | [MongoDB Shell (mongosh)](https://www.mongodb.com/docs/mongodb-shell/) | 手动查看数据库 | [Download mongosh](https://www.mongodb.com/try/download/shell) | `mongosh --version` | | [Docker Engine](https://docs.docker.com/engine/) 和 [Docker Compose](https://docs.docker.com/compose/) | 在容器中运行应用和 MongoDB | [Install Docker Engine](https://docs.docker.com/engine/install/) | `docker --version` 和 `docker compose version` | | [WSL](https://learn.microsoft.com/windows/wsl/) 2.1.5 或更高版本（仅限 Windows） | 在 Windows 上的 Linux 中运行 Docker | [Install WSL](https://learn.microsoft.com/windows/wsl/install) | `wsl --version` | | [Playwright](https://playwright.dev/) Chromium | 浏览器测试 | [Install browsers](https://playwright.dev/docs/browsers#install-browsers)：`npx playwright install chromium` | `npx playwright --version` |

Angular CLI、TypeScript、ESLint 和测试运行器会通过 npm install 安装到项目中，因此无需单独安装；npx ng version 可显示 Angular 版本。

脚本

npm run dev      在 3000 端口启动 Angular 开发服务器并实时重新加载；将 /api 转发到
                 4000 端口的 API 服务器，该服务器会在服务器代码变更时重启
npm run build    将客户端构建为生产版本并输出到 dist/glazecalc/browser，然后将每种语言的
                 公共页面渲染到 dist/glazecalc/prerendered（docs/seo-plan.md）
npm start        构建后，在 3000 端口（PORT）启动一个同时运行应用及其 API 的服务器
npm run seed     将标准材料、添加剂和建议载入 MONGODB_URI
npm run lint     使用 ESLint 检查代码
npm run typecheck  检查服务器的 TypeScript（Node 会直接运行，不进行编译）
npm run format   使用 Prettier 格式化文件（npm run format -- .）

npm run seed 会替换 ID 相同的标准记录，因此数据文件变更后可以安全地再次运行，并且不会影响用户自己的条目。所有脚本都可在任何 shell 中运行，包括 PowerShell 和 cmd。

测试

命令	运行内容
npm test	服务端和化学测试（Mocha），并行运行各文件（每个核心使用一个工作进程，但会留出一个；--jobs 可设置进程数）。每个工作进程都会在自己的进程内用一个空闲端口运行应用，并使用独立的数据库（glazecalc_test_w0、_w1，依此类推；每个文件运行前清空，运行后删除）；只需运行 mongod。
npm run test:client	Angular 单元测试（Vitest），无需服务端或数据库。
npm run test:e2e	浏览器和无障碍测试（Playwright 和 axe），由多个工作进程并行运行（使用一半的核心数；E2E_WORKERS 可设置工作进程数），共用一个服务端。如果 dist/ 比其源文件旧，则会构建应用（可用 E2E_BUILD=always 或 never 覆盖）；应用运行在端口 3100（E2E_PORT），使用会重置的 glazecalc_e2e 数据库（E2E_MONGO_URI）。只需安装一次 Chromium：npx playwright install chromium。
npm run test:e2e:linux	在 Docker 中运行 Linux 浏览器测试，使用 CI 运行测试时所用的同一 Playwright 镜像，因此在此处通过的布局在 CI 中也会通过。测试当前工作树，包括未提交的更改，并将失败的内容复制到 test-results-linux/。在 Windows 上会通过 WSL 运行，WSL 内需要安装 Docker。
npm run test:e2e:both	同时在本机和 Linux 上运行浏览器测试，各使用四分之一的核心数（E2E_WORKERS 可分别设置两次运行的工作进程数），并在每行输出中标记其来源。两次运行互不共享内容，因此所需时间约等于较慢的一次。
npm run check:i18n	检查消息：应用使用的每个键都有英文版本，且每条英文消息都被使用；翻译保留英文版本中的占位符、标签和复数形式；代码中编写的英文内容是最新的（如何编写文本）。
npm run i18n:sources	为译者写出代码和数据中所用消息的英文版本（服务端、化学、标准记录、联系方式和区域数据），并移除所有基于已更改英文内容的翻译（docs/translating.md）。如果有未提交的翻译更改，则会拒绝运行（--force 可覆盖）；-- --dry-run 可显示将要进行的更改。
npm run test:all	在本机运行服务端、Angular 和浏览器测试。
npm run test:all:linux	运行服务端和 Angular 测试，然后在 Linux 上运行浏览器测试。推送任何会更改布局或打印效果的内容前，请运行此命令。
npm run test:coverage 和 npm run test:client:coverage 会生成覆盖率报告，npx playwright show-report 会打开浏览器测试结果。GitHub Actions 会在推送到 master 和提交拉取请求时，针对 MongoDB 9 服务容器运行 lint、格式检查、npm audit、构建和全部三套测试，并构建和检查 Docker 镜像（.github/workflows/ci.yml）。各项作业会并行运行，浏览器测试会分到三个运行器（--shard）上执行，测试报告随后会合并为一份（playwright-report 制品）。

项目结构

client/           Angular 22 应用（独立组件、signals、不使用 zone.js）
  app/core/         API 访问、登录和试用、路由守卫、数据模型
  app/i18n/         语言：加载消息、地址中的语言、AI 提示
  app/pages/        每个页面各有一个文件夹：主页、配方、材料、添加剂、烧制……
  app/shared/       页面标题、消息、选项列表
  public/           图标、图片、清单和 robots.txt，复制到构建产物中
  public/i18n/      各语言的消息和 Markdown 指南
  i18n-fingerprints/  每份译文所依据的英文原文
  styles.scss       基于 Bootstrap 5 的配色方案和深色模式
lib/chemistry/    釉料化学：摩尔质量、材料分析、单位分子式
lib/recipe/       应用、服务和 MCP 工具共用的配方工具：用量、分析、限制、
                  检查、替代、混合（ADR 19）
lib/cones/        测温锥（Orton、SK）和配方的烧制
lib/regions/      各地区和语言，以及指南中每个国家/地区的信息：
                  联系对象、商店、二氧化硅限值、食品接触规则
lib/pages.js      值得在搜索中查找的页面（站点地图、服务、预渲染）
lib/mfa.js        双步登录的服务和应用共用的数字
server/           API 服务，使用 TypeScript 编写，由 Node 直接运行（无需构建步骤）
  main.ts           启动服务：连接 MongoDB、监听请求并正常关闭
  app.ts            Express 应用：`/api` 下的 API，其余请求由构建后的客户端处理，
                    以及为每种语言生成的站点地图（`/sitemap.xml`）
  routes/           账户、密码重置、试用，以及 records.ts：用户保存的七种
                    记录，由一个路由工厂提供服务
  lib/              登录令牌、记录路由、试用限额和清理、邮件、日志记录
  mcp/              面向 AI 助手的 MCP 服务（`/mcp`）：工具、提示词和指南
  models/           Mongoose 模式
  test/             服务和化学测试（Mocha）
e2e/              浏览器和无障碍测试（Playwright、axe）
data/             标准材料、添加剂和建议，由 npm run seed 加载
scripts/          开发运行器（npm run dev）、seed 脚本、消息检查及源文件
                  （npm run check:i18n、i18n:sources）、在 Linux 上运行的浏览器测试
                  （npm run test:e2e:linux），以及一个向资料库添加记录的脚本
Dockerfile, compose.yaml
                  生产镜像，以及在容器中运行的应用和 MongoDB
deploy/           EC2 上的生产部署：Compose 文件、nginx、cloud-init、部署和备份
                  脚本、AWS 策略和设置命令
docs/             决策记录（adr/）、案例研究、翻译计划和指南
                  （translating.md、translations/）、设置说明
.github/          CI、镜像发布和部署工作流、Dependabot

Docker 和部署

Dockerfile 构建生产映像：基于 Debian slim 的 Node 24，以非 root 用户运行，并在 /api/health 上执行健康检查，同时检查数据库。compose.yaml 使用 MongoDB 9 运行应用，并将数据保存在命名卷中：

APP_SECRET=<long random string> docker compose up -d --build
docker compose run --rm app node scripts/seed-standard.js    # standard data, once
docker compose logs -f app

应用仅发布在 127.0.0.1:3000 上；要公开访问，请在前面放置反向代理，因为 Docker 发布的端口会绕过 ufw。AWS 生产环境的部署步骤详见 deploy/README.md 和 deploy/aws/README.md。在 Windows 上，Docker Engine 在 WSL 中运行：docs/wsl-local-deploy-debian.md 记录了在 WSL Debian 中进行设置的注意事项。

当其他人能够访问应用时，请将 APP_SECRET 设为较长的随机值（生产环境必需；更改后会使所有人退出登录），设置 MAIL_TRANSPORT 和 SMTP_URL 以发送密码重置邮件，并将 SITE_URL（原为 APP_URL）设为用户打开应用时使用的地址，邮件中的链接也会使用此地址。将这些变量放入环境或 .env 文件中；compose.yaml 会将它们传递给应用（.env.example 介绍了每个变量）。登录、注册、试用和密码重置都会按客户端地址进行速率限制；使用反向代理时，应用会信任该地址的一个跃点 X-Forwarded-For。

更多信息

• 决策记录：说明项目采用当前构建方式的原因。
• 更新日志。
• 案例研究：重振一款 2017 年的应用。
• 发现问题或有想法？提交问题。

Glazecalc 基于 MIT License 开源。