Kimai 部署指南：开源工时记录系统，自建项目计费平台

Kimai 是一个开源的工时追踪系统，支持按项目、客户、活动分类记录时间，自动生成发票，非常适合自由职业者、小型设计/开发工作室、需要向客户计费的团队。SaaS 版本同类工具（如 Toggl、Harvest）每人每月都要收费，自建 Kimai 完全免费，功能一点不少。

适用场景

• 自由职业者记录各客户的工时，月底生成发票
• 设计/开发团队统计每个项目的工时成本
• 公司内部工时合规记录
• 多人团队的工时汇总报表

服务器配置

规格	推荐
CPU	1 核
内存	512MB
硬盘	10GB

非常轻量，可以和其他服务共用一台机器。我把 Kimai 和 Monica、Actual Budget 等工具放在同一台 雨云服务器 rainyun+com 入门款机型上，总内存用量不到 1GB。注册填优惠码 2026off 领 5 折优惠券，比 Toggl Business 版便宜 99%。

Docker Compose 部署

mkdir -p /opt/kimai

cat > /opt/kimai/docker-compose.yml << 'EOF'
version: "3.8"

services:
  sqldb:
    image: mysql:8.0
    container_name: kimai_db
    volumes:
      - mysql:/var/lib/mysql
    environment:
      - MYSQL_DATABASE=kimai
      - MYSQL_USER=kimai
      - MYSQL_PASSWORD=数据库强密码
      - MYSQL_ROOT_PASSWORD=Root强密码
    command: --default-storage-engine innodb
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin -u kimai -p数据库强密码 ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  kimai:
    image: kimai/kimai2:apache
    container_name: kimai
    ports:
      - "8001:8001"
    environment:
      - ADMINMAIL=admin@你的域名.com
      - ADMINPASS=管理员强密码
      - DATABASE_URL=mysql://kimai:数据库强密码@sqldb/kimai?charset=utf8mb4&serverVersion=8.0.32
      - TRUSTED_HOSTS=kimai.你的域名.com,localhost
      - MAILER_URL=smtp://邮件账号:邮件密码@smtp.你的邮件服务商.com:587?encryption=tls
      - MAILER_FROM=kimai@你的域名.com
    volumes:
      - kimai-data:/opt/kimai/var/data
      - kimai-public:/opt/kimai/public/avatars
    depends_on:
      sqldb:
        condition: service_healthy
    restart: unless-stopped

volumes:
  mysql:
  kimai-data:
  kimai-public:
EOF

cd /opt/kimai
docker compose up -d

等待约 1 分钟初始化完成：

docker compose logs -f kimai
# 看到 apache2 is ready 后再访问

配置 HTTPS（Caddy）

sudo tee -a /etc/caddy/Caddyfile << 'EOF'

kimai.你的域名.com {
    reverse_proxy localhost:8001
}
EOF

sudo systemctl reload caddy

初始设置

访问 https://kimai.你的域名.com，用 admin@你的域名.com 和管理员密码登录。

基础配置顺序

1. 创建客户（Customers）
2. 创建项目（Projects）并关联客户
3. 创建活动类型（Activities）：如「开发」「设计」「会议」「测试」
4. 邀请团队成员（Users）

核心使用流程

开始计时

首页 → 开始计时
选择：项目 → 活动 → 描述（可选）
→ 开始

计时器在后台运行，可以随时暂停或停止。

手动添加工时

工时单 → 新建工时单
填写：开始时间、结束时间、项目、活动

查看工时统计

报表 → 工时统计
筛选条件：日期范围、客户、项目、员工
导出格式：Excel / CSV / PDF

发票生成

Kimai 内置发票模板，可以直接生成发票 PDF：

发票 → 创建发票
- 选择客户
- 设置账单日期和截止日期
- 选择要纳入发票的工时单
- 设置单价（按小时或固定价格）
→ 预览 → 导出 PDF

自定义发票模板（HTML/Twig 格式）：

管理 → 发票模板 → 新建模板

团队功能

用户角色

角色	权限
Super Admin	全部权限
Admin	管理系统设置
Teamlead	管理团队成员的工时
User	只能管理自己的工时

审批流程

管理员可以审批员工的工时记录，确认后不可修改：

工时单 → 审批 → 批量审批

移动端访问

Kimai 的 Web 界面支持响应式布局，手机浏览器访问效果很好，随时可以开始/停止计时。

也可以使用第三方 Kimai 移动 App（iOS/Android），连接到你的服务器地址。

插件扩展

Kimai 有丰富的免费插件：

# 在容器内安装插件
docker exec -it kimai bash

cd /opt/kimai
# 常用插件
composer require kimai/kimai-plugins:^2.0
bin/console kimai:plugin:install

常用插件：

• Translation：更多语言支持
• ExpenseBundle：记录项目支出
• MetaFieldsBundle：自定义字段
• CustomCSSBundle：自定义样式

数据备份

cat > /opt/backup_kimai.sh << 'EOF'
#!/bin/bash
docker exec kimai_db mysqldump -u kimai -p数据库强密码 kimai > /backup/kimai-$(date +%Y%m%d).sql
find /backup -name "kimai-*.sql" -mtime +30 -delete
EOF

chmod +x /opt/backup_kimai.sh
echo "0 2 * * * /opt/backup_kimai.sh" | crontab -

更新

cd /opt/kimai
docker compose pull
docker compose up -d

---

Kimai 对自由职业者和小型工作室来说是非常实用的工具。把工时记录和发票生成结合在一起，月底对账和开票效率大大提高。部署在雨云服务器上，所有客户数据、工时记录都在自己手里，不用担心第三方 SaaS 服务的数据安全问题。