opshomenoc/payroll-server repository overview

⁠OpsHome Payslip Server

免费私有化部署的企业工资条服务端，配合官方 iOS App 使用。

Self-Hosted Community Edition · Company-managed payroll data · Official iOS client

企业在自己的服务器上管理员工、工资条及发薪流程；员工通过官方 OpsHome Payslip iOS App 查阅、核对工资，并提交薪资异议。

• 镜像：opshomenoc/payroll-server
• 官方网站⁠
• 官方 iOS App⁠

⁠主要功能

• 企业自主管理：自建服务器，内置数据库。
• 灵活导入：导入 Excel，映射工号、姓名、实发工资及其他薪资项目。
• 发薪流程：按职责分配导入、审核及发布权限。
• 员工核对：查看工资条、确认核对无误、提交异议及接收答复。
• 设备管理：配对审批、设备绑定及撤销。
• 企业品牌：自定义企业名称与 Logo。
• 备份还原：通过 Web 后台创建加密快照，并在新环境中上传还原。

官方 iOS App 提供本地加密缓存、离线查阅及系统身份验证等防护。具体功能及客户端授权以当前发行版本和 App Store 说明为准。

⁠部署要求

• Linux 主机，已安装 Docker Engine 和 Docker Compose 插件。
• 企业公网域名及公网可信 HTTPS 证书。
• HTTPS 反向代理及持久数据卷。
• 正常的系统时间、足够的磁盘空间及管理员 TOTP 验证器。

员工 App 必须通过公网域名和可信 HTTPS 连接。内网 IP 自签名证书仅用于支持该功能的管理后台访问，不能用于 App 配对。

容器内部 HTTP 端口为 8000，持久数据目录为 /data。本镜像不是运行后即可自动创建企业和管理员的网页初始化向导，首次部署须先执行下方初始化命令。

⁠镜像标签

以下示例使用 latest 便于首次拉取。正式部署前，建议从本仓库 Tags 页面选择已发布的数字版本并固定，也可固定镜像 digest。

⁠1. 准备配置

mkdir -p ~/opshome-payroll
cd ~/opshome-payroll

创建 compose.yml：

services:
  payroll:
    image: ${PAYROLL_IMAGE:?Set the official image and version}
    ports:
      - "127.0.0.1:8098:8000"
    environment:
      PAYROLL_LISTEN: "0.0.0.0:8000"
      PAYROLL_DATABASE_URL: "sqlite:////data/payroll.sqlite3"
      PAYROLL_PUBLIC_URL: ${PAYROLL_PUBLIC_URL:?Set the public HTTPS origin}
      PAYROLL_TRUSTED_HOSTS: ${PAYROLL_TRUSTED_HOSTS:?Set allowed hosts}
      PAYROLL_PROXY_HOPS: "1"
      PAYROLL_TRUSTED_PROXY_CIDRS: ${PAYROLL_TRUSTED_PROXY_CIDRS:?Set actual proxy source CIDRs}
      PAYROLL_DEV_MODE: "0"
      PAYROLL_CLIENT_LICENSE_ALLOW_SANDBOX: "0"
    volumes:
      - payroll-data:/data
    read_only: true
    tmpfs:
      - /tmp:size=320m,mode=1777
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    restart: unless-stopped

volumes:
  payroll-data:
    name: opshome-payroll-data

创建 .env，替换企业域名与可信代理来源：

PAYROLL_IMAGE=opshomenoc/payroll-server:latest
PAYROLL_PUBLIC_URL=https://payroll.example.com
PAYROLL_TRUSTED_HOSTS=payroll.example.com,localhost,127.0.0.1
PAYROLL_TRUSTED_PROXY_CIDRS=REPLACE_WITH_ACTUAL_PROXY_SOURCE_CIDRS

REPLACE_WITH_ACTUAL_PROXY_SOURCE_CIDRS 是必须替换的占位值。填写容器实际看到的反向代理来源 CIDR；多个来源用逗号分隔。宿主机反代经 Docker 网桥连接时，来源可能为网桥网关，而非 127.0.0.1。不要通过信任全部地址来解决访问问题。

chmod 600 .env
docker compose config --quiet
docker compose pull

此示例仅监听宿主机回环地址，适用于反代运行在同一宿主机的场景。不同主机或容器内反代需相应调整网络和监听地址，并限制上游端口的访问来源。

⁠2. 首次初始化

仅对首次新部署执行，按顺序逐条运行。

docker compose run --rm payroll db-upgrade

docker compose run --rm payroll init-company \
  --name '企业名称' --region CN

docker compose run --rm payroll create-admin --username admin

docker compose up -d
docker compose ps
docker compose logs --tail=100 payroll

中国大陆地区使用 CN，香港地区使用 HK。创建管理员时按提示设置密码，并将 TOTP 登记信息添加至验证器，妥善保管。

如当前账户没有 Docker 操作权限，在上述 Docker 命令前加 sudo。

⁠3. 接入 HTTPS

在反向代理上配置企业域名与可信证书，将请求转发至：

http://127.0.0.1:8098

Nginx 已有 HTTPS 站点中的转发示例：

location / {
    proxy_pass http://127.0.0.1:8098;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $remote_addr;
}

以上不是完整的 TLS 站点配置。多层代理需按实际拓扑配置可信来源、代理跳数及转发头。上传备份时，还需确认反代与前置网关允许相应的上传大小和处理时间。

不要给员工 App API 或官方授权回调添加必须由浏览器完成的交互式质询。

通过企业 HTTPS 地址登录后台，配置业务角色和员工资料，再由员工使用官方 iOS App 按提示配对。

⁠数据持久化

业务数据库及服务端身份密钥保存在 /data，本示例对应命名卷 opshome-payroll-data。

• 重建容器时，保留原数据卷及配置。
• docker compose down 通常保留本示例中的命名数据卷，所以重新启动后原账户和工资数据仍在，这是正常行为。
• docker compose down -v 或删除数据卷会导致持久数据丢失，不用于日常升级。
• 请勿随意删除、替换数据目录中的身份密钥。

⁠备份与后台还原

⁠创建备份

系统管理员登录 Web 后台，进入 「加密备份与灾备还原」：

/admin/system/backups

设置独立备份口令，下载 .enc 快照，将文件保存到服务器之外，并与口令分开保管。部署配置、DNS、证书、反代配置及 .env 应另行保存。

⁠在新环境还原

1. 优先使用与备份时相同的镜像版本，并准备新数据卷。
2. 保持原企业 HTTPS 地址及匹配的信任配置。
3. 按首次初始化流程建立临时企业及临时管理员，再启动服务。
4. 使用临时管理员登录后台，在上述页面上传原 .enc 文件。
5. 输入备份口令及确认文字 RESTORE，执行校验并还原。
6. 完成后，使用备份中的原管理员、原密码和原 MFA重新登录。

还原会替换目标环境的数据，不能作为合并操作。临时企业及临时账号会被备份内容替换。快照仅包含备份时点的数据；保留已有 App 绑定，先核对后台数据及设备连接，再恢复正式使用。

⁠保留数据升级

先通过后台下载备份，再将 .env 中的 PAYROLL_IMAGE 改为目标发行版本：

docker compose pull
docker compose stop payroll
docker compose run --rm payroll db-upgrade
docker compose up -d
docker compose logs --tail=100 payroll

升级时复用原数据卷、域名和配置，不要重新执行 init-company 或 create-admin。修改 .env 后需要重建容器以应用环境变量，单独执行 docker restart 不会应用新变量。

⁠隐私与数据管理

我们提供经过验证并正式发布的服务器镜像、具备安全防护的官方 iOS App 及后续软件更新服务。

自建服务器由使用方自行部署和管理。员工资料、薪资明细及其他业务数据由使用方自行保管；我们不接收、托管或管理这些业务数据，也无法通过本产品的日常服务访问你的自建服务器或其中的数据。

产品采用加密与访问防护机制保护数据，但不承诺绝对安全。使用方负责运行环境、权限、设备安全、备份、恢复及数据保存安排。软件更新不能替代使用方的安全管理。

⁠许可与安全使用

Self-Hosted Community Edition 表示可免费私有化部署，不表示开源或放弃软件许可限制。服务端须配合官方 iOS 客户端使用，具体授权范围以发行版附带的许可条款为准。

不得用于违法活动、未经授权访问他人系统或数据，或破坏安全机制。除适用法律明确允许的情形外，未经授权不得进行反编译、反汇编、逆向工程、破解、篡改、绕过授权验证或分发修改版本。

⁠常见问题

删掉容器，为什么旧账号仍能登录？
数据保存在命名卷中，删除容器不会自动清空数据。

首次启动后没有管理员，怎么办？
先执行 db-upgrade、init-company、create-admin，再启动服务。当前版本没有网页初始化向导。

能使用 IP 地址或自签名证书连接 App 吗？
不能。App 配对及连接需要企业公网域名和公网可信 HTTPS 证书。

还原后临时管理员无法登录？
临时账号已被备份内容替换，请使用原备份中的管理员及对应 MFA。

客户端需要单独付费吗？
服务端可免费自建；官方 iOS 客户端的试用与购买规则以 App Store 及 App 内说明为准。

⁠支持

产品信息、客户端及联系入口见上方官网与 App Store 链接。反馈部署问题时，请提供镜像标签、部署方式、错误码及已脱敏日志；不要提交真实工资条、数据库、备份文件、密码、MFA 信息或私钥。